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.
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:
Example1: |
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: 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: |
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:
|
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;... '
|
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. |
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); } |