EPLAN.EPLAN21.FORMGEN.GENERATE_PAGE

Contents

Description

Command for generating pages via the form generator of EPLAN 21.

The form generator functions for all the generation types, i.e. also for file generation, in accordance with the same principle. The first step is to collect all the relevant objects whose data can be output in accordance with the form type. Certain forms support two-stage collecting meaning that a list of the lists is practically drawn up. Example: The terminal diagram first collects all the terminal strips (so-called header data), then all the terminals (so-called data) for each individual strip. The table of contents collects all the pages of a project in one stage, the bill of materials (DTs) collects all the devices, the parts list (parts) collects all the parts, etc. In the second step the collected objects are filtered. Header data and data are filtered by separate criteria. In the third step the filtered objects are sorted. There are, in turn, separate criteria for header data and data. In the next step the retainers placed in the form are evaluated in accordance with the properties set in the form, such as the number of lines, number of columns etc., and the value is placed on the new page at the calculated position or, when a file is generated, output to the target file in the form of a data field.

When pages are generated, the values are processed again, so that certain generated values are converted to graphics elements, for example, graphic jumpers in the terminal diagram.

If existing pages are overwritten, the old pages are replaced by the new ones. If new pages are appended, meaning not overwritten, the pages are sorted into the sequence of existing pages on the basis of the general sorting criteria. Sorting criteria are always those properties which occur in the format for the complete page name (project property 2234). Values for these sorting criteria can be transferred to the command as parameters.

Parameters

The following parameters have the EPL_PARAM_FORMGEN_GENERATE_BASE_prefix. These parameters also apply for the EPLAN.EPLAN21.FORMGEN.GENERATE_FILE command.

ParameterID Type Description
PROJECT [IN]
EplHandle
Handle to the project in which the pages are to be created or overwritten.
NEW_RUNID [OUT]
Integer
ID of the generation run just completed or 0 not set when the run has been completed. It is at present only available for the commands EPLAN.EPLAN21.FORMGEN.GENERATE_PAGE and EPLAN.EPLAN21.FORMGEN.REGENERATE, but not for EPLAN.EPLAN21.FORMGEN.GENERATE_FILE.
FORM [IN]
String
Name of the form to be used.
FORMULAR [IN]
String
Obsolete description for the parameter EPL_PARAM_FORMGEN_GENERATE_BASE_FORM with the same meaning. Please do not use it any longer. This parameter may be deleted in a future version of the API.
FILTERLIST [IN, OPTIONAL]
String
The filter list defines criteria which the objects have to fulfill before generating can be carried out. All the data objects are included, if no filter list is specified. The filter list is based on the principle of the matches of the property values with filter expression. Filter expressions are interpreted in accordance with the property type. Normally filter expressions are regular expressions: In the case of date properties the filter expression is interpreted as a date range (refer to the EPLAN 21 online help).

The list has the following structure in detail:
<n=filter><v=2>;Property-ID[<IndirectProperty>]:[blank|!]Filter-expression

Example1: <n=filter><v=2>;5<53>: ^A filters all the objects whose name (Property 5) of their indirect projects (Indirect Property 53) begins with A.

Example2: <n=filter><v=2>;5:!^A filters all the objects whose name (Property 5) begins not (!) with A.

HEADERFILTERLIST [IN, OPTIONAL]
String
This filter list functions in accordance with the same principle as the filter list of the parameter FILTERLIST, except that it is used for the header data objects instead of for the data.
SORTLIST [IN, OPTIONAL]
String
The sorting list specifies the criteria to be used for sorting the data objects. A criterion is defined as a property-request term, i.e. either a property number or a term for an indirect property (format: "Property-Id Property-Index < Detour-Id Detour-Index >".

Example: 6;5 sorts the objects primarily in accordance with the description (Property 6) and secondarily (i.e. if the description is identical) in accordance with the name (Property 5).
Example for parts list (parts): 5<8031>;5 sorts the parts in accordance with the name of the device to which they are assigned and then, if these are the same, in accordance with the parts names.

The comparison of two properties is carried out on the basis of the property type. Numbers are compared numerically, date values for the time, all others by a special alphanumerical method which groups the numerical components and alphabetical components and compares them by groups, with numerical groups being compared numerically. Numerically identical groups are compared by their length, with the longer blocks being sorted in before the shorter ones.

Example: A2 before X1.001 before X1.01 before X2

HEADERSORTLIST [IN, OPTIONAL]
String
This sorting list functions in accordance with the same principle as the sorting list of the parameter SORTLIST, except that it is used for the header data objects instead of for the data.
HEADERMANSEL [IN, OPTIONAL]
Boolean
Must be set to "1", if only header data objects specified by the HEADERMANSELITEMS parameter are to be used. Otherwise the value of the parameter should be set to "0" or the parameter should not be set.
HEADERMANSELITEMS [IN, OPTIONAL]
String
If the value of HEADERMANSEL is "1", this string is interpreted as a semicolon-separated list of object identifiers. An object identifier consists of the index of the object, a colon and a string which corresponds to the value of the object property EPL_PROPERTY_GENE_UNIQUE_STRING_REP (Property 16). Any colon, backslash or semicolon occuring in the identifying string must be preceeded by a backslash. This "manual selection" is only possible for the terminal diagram. This means that it can be used to generate a terminal diagram for a defined group of terminal strips which cannot be filtered by means of regular expressions. The parameter may not be set or must be empty for all other page types.
SOURCEFILENAME [IN, OPTIONAL]
String
File name of the input file with complete path. An input file is only expected by a "Text view" page type. The parameter may not be set or must be empty for all other page types. The form under the property EPL_PROPERTY_PAGE_GENSOURCEFILENAME (property 3284) contains a suggestion for this parameter.

The following parameters have the EPL_PARAM_FORMGEN_GENERATE_PAGE_prefix.

ParameterID Type Description
OVERWRITE_RUNID [IN, OPTIONAL]
Integer
ID of the generation run which is to be overwritten. The ID of a generation run is saved in generated pages under the property EPL_PROPERTY_PAGE_FORMGEN_RUNID (Property 3245). This parameter has only to be set, if the generation is to be carried out in the "Overwrite" mode. "Overwrite" mode means that all the pages with the specified ID are collected and re-used before generation. Surplus pages will be deleted without a prompt. Missing pages are created. Re-using pages means that all the instances on the pages are deleted, all the properties of the page are retained (if necessary, the description of the page is re-assigned automatically). If the ID is not found in the project, generation is aborted with the error EPL_ERR_FORMGEN_INVALID_RUNID.
PLOTFRAME [IN, OPTIONAL]
String
Name of the plot frame which is to be assigned to the page. If this parameter is not set, or if it is empty, the plot frame assigned in the form is used for new pages. In case there is no plot frame within the form, the default plot frame of the project is used. The plot frame of re-used pages remains unaffected if this parameter is empty.
SEPERATEPAGES [IN, OPTIONAL]
Boolean
Indicates if a page feed is to be enforced in the case of changed header data. This parameter is only sensible if the respective form type supports header data as, e.g. the terminal diagram in contrast to the table of contents.
GROUPLIST [IN, OPTIONAL]
String
List of properties the modification of which is to enforce a page feed. Only the properties according to which the data are sorted make sense here.
AUTODESCRIPTION [IN, OPTIONAL]
Boolean
Indicates if the page description is to be automatically assigned. If set to yes, the page descriptions are generated according to the format string as entered in the form (property 6029). If no format string has been entered in the form, a default format string is used: "<3001>: <3142> (<3143> - <3144>)". The properties in the format string have the following meaning:
Property 3001
Page type/form type
Property 3142
Name of the first header object on this page
Property 3143
Name of the first data object on this page
Property 3144
Name of the last data object on this page
If this flag has not been set, the descriptions of overwritten pages are taken over. If set to no, the page descriptions of the pages to be overwritten are retained and no description is assigned to new pages. Note: If no description is set for a certain page, the project description is automatically displayed.
SORTINGPROPS [IN, OPTIONAL]
String
List of property values that are set in the pages and serve the purpose of sorting the pages when appending pages (in contrast to the Overwrite action). All properties that occur in the format for the complete page name (property 2234) are permitted. Format of the list: 'PropertyId:Value;PropertyId:Value;...'

Error Messages

The eplExecuteCommand function returns EPL_OK if the objects could be successfully exported.

If the command fails, eplExecuteCommand returns the value EPL_ERROR. In this case, the error log can contain the following errors:

ErrorID Description
EPL_ERR_GENERAL An unexpected exception error has occurred.
EPL_ERR_CANCELED The process was aborted by the user.
EPL_ERR_FG_FORM_INVALID No form could be found for the form name specified.
EPL_ERR_FG_FORMTYPE_INVALID The specified form has a form type not supported by the form generator (form property 6001). The creator of the form can enter any page type as the type: However, only a subset of all the page types can be processed by the form generator. Example: Forms of the "Free graphics" form type cannot be used for generation.
EPL_ERR_FG_PROJECT_INVALID The project handle is invalid.
EPL_ERR_FG_RUNID_INVALID No pages of the specified generation-run ID could be found. This error can only occur in the Overwrite mode.
EPL_ERR_NO_RIGHT The current user group does not allow for using the Form generator or modifying and creating pages.

Example

void generatePage(EplSession s)
{
        EplHandle cmd = eplCreateCommand(s,
                L"EPLAN.EPLAN21.FORMGEN.GENERATE_PAGE");

        //Set parameters  ...

        if (eplExecuteCommand(s, cmd) == EPL_OK)
        {
                // Read out return parameters ...
        }

        eplCloseObject(s, cmd);
}

Reference