EPLAN.EPLAN21.ELEMENT.CREATE_AND_INSTANTIATE

Contents

Description

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.

Parameters

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:
  • Terminal: Terminals require a handle to the terminal strip.
  • Pin: Handle to a plug component.
  • Potential point/potential terminal: Handle to a potential definition.
  • Interruption point: Handle to a interruption point list:
  • I/O terminal: Handle to PLC box.
  • Device end terminal: Handle to black box.
  • Contact: Optional handle to coil component.

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.
  • Value "0". The command places a (created/existing) element on a page.
  • Value "1". The command creates an element, but it is not placed.
BOXTYPE [IN, OPTIONAL]
String
If the defined symbol specifies a box, this parameter must give the type of the box.
Possible values are:
  • "0": Black box.
  • "1": Location box.
  • "2": PLC box.
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:
  • "0": Undefined
  • "1": Input
  • "2": Output
  • "3": Analog input
  • "4": Analog output
  • "5": Timer
  • "6": Flag
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.

Error Messages

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".

Example

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;
}

Reference