This command allows you to create and directly place schematic elements by using symbols. Furthermore, already existing components can be placed on pages, or elements can be created without being placed.
The EPLAN.EPLAN21.ELEMENT.CREATE_AND_INSTANTIATE command is called up via the API functions as specified in the EPLAN 21 API.
All parameters have the prefix "EPL_PARAM_ELEMENT_CREATE_AND_INSTANTIATE_".
ParameterID | Type | Description |
---|---|---|
PROJECT | [IN] EplHandle |
Handle of the project/macro in which the elements are to be created. |
PAGE | [IN, OPTIONAL] EplHandle |
Handle to the page on which the created element is to be placed. The parameter is optional if an element is merely to be created but not to be placed. If the parameter is specified, properties (e.g. plant) for a device which is possibly to be created are read from the page |
X_POS | [IN, OPTIONAL] String |
X coordinate on the page. At this point the element is inserted into the page. If a device is generated, the parameter is used to read further properties such as path for the device from the page. The parameter is ignored if an element is only created but not placed. |
Y_POS | [IN, OPTIONAL] String |
Y coordinate on the page. At this point the element is inserted into the page. If a device is generated, the parameter is used to read further properties such as path for the device from the page. The parameter is ignored if an element is only created but not placed. |
X_EXT | [IN, OPTIONAL] String |
X-extension of the element to be generated. Some elements such as cable lines or black boxes have an extension. The X-part is given in this parameter. The value "0" represents the left-hand margin. The parameter is ignored if an already existing element is to be placed. |
Y_EXT | [IN, OPTIONAL] String |
Y-extension of the element to be generated. Some elements such as cable lines or black boxes have an extension. The Y-part is given in this parameter. The value "0" represents the bottom margin. The parameter is ignored if an already existing element is to be placed. |
SYMFILE | [IN, OPTIONAL] String |
Name of symbol file. If a schematic element is to be created, the symbol has to be identified via symbol file name, symbol number and symbol variant. The symbol file must exist in the database; if necessary, it can be added to the project. The parameter is ignored if an already existing element is to be placed. |
SYMNR | [IN, OPTIONAL] String |
Number of symbol. If a schematic element is to be created, the symbol has to be identified via symbol file name, symbol number and symbol variant. The symbol number starts with the value "0". The parameter is ignored if an already existing element is to be placed. |
SYMVAR | [IN, OPTIONAL] String |
Symbol variant. If a schematic element is to be created, the symbol has to be identified via symbol file name, symbol number and symbol variant. "0" to "4" are valid values. The parameter is ignored if an already existing element is to be placed. |
PARENT | [IN, OPTIONAL] EplHandle |
Handle to the parent object. Some schematic elements such as terminals, pins, interruption points require a reference to a parent object such as terminal strip, plug component or interruption-point list. The following element types require a handle to a parent object:
The parameter is ignored if an already existing element is to be placed. |
TARGET_DEVICETAG | [IN, OPTIONAL] EplHandle |
Handle to a default device. If a schematic element is created, an already existing device can be specified as target. The new element - provided that it is a component - is inserted in the defined component. The parameter is ignored if an already existing element is to be placed. |
DT_PROPERTIES | [IN, OPTIONAL] Iterator |
Handle to an iterator for properties. If a new device was generated during the creation of an element, the properties will be transferred to this new device. The parameter is ignored if an already existing element is to be placed. |
COMPONENT | [IN, OPTIONAL] EplHandle |
Handle to a default component. If an already existing component is to be placed, the handle to this component has to be handed over in this parameter. The parameter is ignored if an new element is to be created. |
CREATE_ONLY | [IN, OPTIONAL] String |
By means of this parameter the operation of the command can be controlled.
|
BOXTYPE | [IN, OPTIONAL] String |
If the defined symbol specifies a box, this parameter must give the type of the box. Possible values are:
|
SUBLOCATION_NAME | [IN, OPTIONAL] String |
If the defined symbol and the box type specify a location box, this parameter must give the location this box must contain. Only already existing location designations are permitted. |
PLCTYPE | [IN, OPTIONAL] String |
If the defined symbol and the box type specify a PLC box, this parameter must give the PLC type. Possible values are:
|
RESULT | [OUT] EplHandle |
After the command was successfully executed, this parameter can be used to query the handle to the generated instance. If an element was generated but not placed, this parameter is empty. |
RESULTCOMPONENT | [OUT] EplHandle |
After the command was successfully executed, this parameter can be used to query the handle to the generated component. If an existing element was placed or if the generated element was not of the component type, this parameter is empty. |
The eplExecuteCommand function returns EPL_OK if the command was executed successfully.
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_NO_RIGHT | The current user group is not allowed to modify the project. |
EPL_ERR_FAILED | The object could not be created. |
EPL_ERR_INVALID_ARGUMENT | The parameter PROJECT or BOXTYPE were invalid. |
EPL_ERR_CREATEPLACE_INVALID_PAGE | The PAGE parameter was invalid or not specified. |
EPL_ERR_CREATEPLACE_INVALID_DEVICETAG | The device specified in the DEVICETAG parameter includes components that cannot be cross-referenced, e.g. terminal strips. |
EPL_ERR_CREATEPLACE_ALREADYPLACED | The component specified in the COMPONENT parameter has already been placed. |
EPL_ERR_CREATEPLACE_MARKED_AS_EXTERN | The component specified in the COMPONENT parameter is marked as external and cannot be placed. |
EPL_ERR_CREATEPLACE_CANT_PLACE | The component specified in the COMPONENT parameter cannot be placed. Note: Terminal strips and plug components cannot be placed. |
EPL_ERR_CREATEPLACE_INVALID_SYMBOLINFO | The symbol information contained in the SYMFILE, SYMNR, SYMVAR parameters is invalid. |
EPL_ERR_CREATEPLACE_INVALID_PARENT | The object specified in the PARENT parameter is invalid. |
EPL_ERR_CREATEPLACE_IS_PROJECTDATA | The element specified via the parameters SYMFILE, SYMNR, SYMVAR must be generated with the commands belonging to "Project data". |
The following example shows a function that creates and places a component and returns a handle to the placed instance.
EplHandle createAndPlace( EplSession session, EplHandle hProject, EplHandle hPage, const wchar_t *xPos, const wchar_t *yPos, const wchar_t *symFile, const wchar_t *symNr, const wchar_t *symVariant) { EplHandle hRet(EPL_ERROR); //Create command EplHandle hCmd = eplCreateCommand(session, L"EPLAN.EPLAN21.ELEMENT.CREATE_AND_INSTANTIATE"); if(hCmd != EPL_ERROR) { eplSetHandleParam(session, hCmd, EPL_PARAM_ELEMENT_CREATE_AND_INSTANTIATE_PROJECT, hProject, 0); eplSetHandleParam(session, hCmd, EPL_PARAM_ELEMENT_CREATE_AND_INSTANTIATE_PAGE, hPage, 0); eplSetParam(session, hCmd, EPL_PARAM_ELEMENT_CREATE_AND_INSTANTIATE_X_POS, xPos, 0); eplSetParam(session, hCmd, EPL_PARAM_ELEMENT_CREATE_AND_INSTANTIATE_Y_POS, yPos, 0); eplSetParam(session, hCmd, EPL_PARAM_ELEMENT_CREATE_AND_INSTANTIATE_SYMFILE, symFile, 0); eplSetParam(session, hCmd, EPL_PARAM_ELEMENT_CREATE_AND_INSTANTIATE_SYMNR, symNr, 0); eplSetParam(session, hCmd, EPL_PARAM_ELEMENT_CREATE_AND_INSTANTIATE_SYMVAR, symVariant, 0); eplSetParam(session, hCmd, EPL_PARAM_ELEMENT_CREATE_AND_INSTANTIATE_CREATE_ONLY, L"0", 0); //Execute command if(eplExecuteCommand(session, hCmd) == EPL_OK) { // Query result: Handle of instance hRet = eplGetHandleParam(session, hCmd, EPL_PARAM_ELEMENT_CREATE_AND_INSTANTIATE_RESULT, 0); if(hRet != EPL_ERROR) hRet = eplCloneHandle(session, hCmd); } eplCloseObject(session, hCmd); } return hRet; } |
The following example shows a function that places an existing component and returns a handle to the placed instance.
EplHandle place( EplSession session, EplHandle hProject, EplHandle hPage, const wchar_t *xPos, const wchar_t *yPos, EplHandle hComponent) { EplHandle hRet(EPL_ERROR); //Create command EplHandle hCmd = eplCreateCommand(session, L"EPLAN.EPLAN21.ELEMENT.CREATE_AND_INSTANTIATE"); if(hCmd != EPL_ERROR) { eplSetHandleParam(session, hCmd, EPL_PARAM_ELEMENT_CREATE_AND_INSTANTIATE_PROJECT, hProject, 0); eplSetHandleParam(session, hCmd, EPL_PARAM_ELEMENT_CREATE_AND_INSTANTIATE_PAGE, hPage, 0); eplSetHandleParam(session, hCmd, EPL_PARAM_ELEMENT_CREATE_AND_INSTANTIATE_COMPONENT, hComponent, 0); eplSetParam(session, hCmd, EPL_PARAM_ELEMENT_CREATE_AND_INSTANTIATE_X_POS, xPos, 0); eplSetParam(session, hCmd, EPL_PARAM_ELEMENT_CREATE_AND_INSTANTIATE_Y_POS, yPos, 0); eplSetParam(session, hCmd, EPL_PARAM_ELEMENT_CREATE_AND_INSTANTIATE_CREATE_ONLY, L"0", 0); //Execute command if(eplExecuteCommand(session, hCmd) == EPL_OK) { // Query result: Handle of instance hRet = eplGetHandleParam(session, hCmd, EPL_PARAM_ELEMENT_CREATE_AND_INSTANTIATE_RESULT, 0); if(hRet != EPL_ERROR) hRet = eplCloneHandle(session, hCmd); } eplCloseObject(session, hCmd); } return hRet; } |
The following example shows a function that creates a component but does not place it. The handle to the created component is returned.
EplHandle create( EplSession session, EplHandle hProject, const wchar_t *symFile, const wchar_t *symNr, const wchar_t *symVariant) { EplHandle hRet(EPL_ERROR); //Create command EplHandle hCmd = eplCreateCommand(session, L"EPLAN.EPLAN21.ELEMENT.CREATE_AND_INSTANTIATE"); if(hCmd != EPL_ERROR) { eplSetHandleParam(session, hCmd, EPL_PARAM_ELEMENT_CREATE_AND_INSTANTIATE_PROJECT, hProject, 0); eplSetParam(session, hCmd, EPL_PARAM_ELEMENT_CREATE_AND_INSTANTIATE_SYMFILE, symFile, 0); eplSetParam(session, hCmd, EPL_PARAM_ELEMENT_CREATE_AND_INSTANTIATE_SYMNR, symNr, 0); eplSetParam(session, hCmd, EPL_PARAM_ELEMENT_CREATE_AND_INSTANTIATE_SYMVAR, symVariant, 0); eplSetParam(session, hCmd, EPL_PARAM_ELEMENT_CREATE_AND_INSTANTIATE_CREATE_ONLY, // 1 => create only L"1", 0); //Execute command if(eplExecuteCommand(session, hCmd) == EPL_OK) { // Query result: Handle of component hRet = eplGetHandleParam(session, hCmd, EPL_PARAM_ELEMENT_CREATE_AND_INSTANTIATE_RESULTCOMPONENT, 0); if(hRet != EPL_ERROR) hRet = eplCloneHandle(session, hCmd); } eplCloseObject(session, hCmd); } return hRet; } |