EPLAN.EPLAN21.PLUG.CREATE

Contents

Description

Command for generating an entire plug. The plug is generated with its pins and the device tag.

The EPLAN.EPLAN21.PLUG.CREATE command is called up via the API functions as specified in the EPLAN 21 API.

Parameters

All parameters have the prefix "EPL_PARAM_PROJECTDATA_CREATE_"!

ParameterID Type Description
PROJECT [IN]
EplHandle
Handle of the project/macro in which the plug is to be generated.
PROPERTIES [IN, OPTIONAL]
Iterator
Handle to an iterator for properties. The identifying properties are copied to the new plug device.
PAGE [IN, OPTIONAL]
EplHandle
Handle of the page from which further identifying properties for the new plug device can be taken, e.g. plant/location.
XPOS [IN, OPTIONAL]
Integer
X-coordinate on the page from which further identifying properties can be read out, e.g. path or location of a location box at this position.
YPOS [IN, OPTIONAL]
Integer
Y-coordinate on the page, see parameter XPOS.
SYMFILE [IN]
String
Name of the symbol file from which the symbol for the plug component is to be taken.
SYMNR [IN]
String
Name of the symbol file from which the symbol for the plug component is to be taken.
SYMVAR [IN]
String
Variant of the symbol from which the plug component is to be generated.
PIN_SYMFILE [IN, OPTIONAL]
String
Name of the symbol file from which the symbol for the pins of the plug is to be taken. If the parameter is empty the first symbol found of the symbol type 'pin' is taken.
PIN_SYMNR [IN, OPTIONAL]
String
Name of the symbol file from which the symbol for the pins of the plug is to be taken. If the parameter is empty the first symbol found of the symbol type 'pin' is taken.
PIN_SYMVAR [IN, OPTIONAL]
String
Variant of the symbol from which the pins for the plug are to be generated. If the parameter is empty the first symbol found of the symbol type 'pin' is taken.
RESULT [OUT]
EplHandle
After the command was successfully executed, this parameter can be used to query the handle of the generated plug component.
RENAMED [OUT]
String
If the device tag of the plug had to be renamed since a device with the same name was already existing, this parameter is set to "1".

Error Messages

The eplExecuteCommand function returns EPL_OK if the plug could be created 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 another parameter was invalid.
EPL_ERR_PROJECTDATA_INVALID_PLUG_SYMBOL The symbol taken for the plug was invalid.
EPL_ERR_PROJECTDATA_INVALID_PIN_SYMBOL The symbol taken for the pins was invalid.
EPL_ERR_PROJECTDATA_NO_PIN_SYMBOL_FOUND No pin symbol was found.

Example

The following example shows a function which creates a plug.

EplHandle
createPlug(EplSession session, EplHandle hProject)
{
        EplHandle hRet(EPL_ERROR);

        //Create command
        EplHandle hCmd = eplCreateCommand(session, L"EPLAN.EPLAN21.PLUG.CREATE");

        if(hCmd != EPL_ERROR)
        {
                eplSetHandleParam(session,
                                  hCmd,
                                  EPL_PARAM_PROJECTDATA_CREATE_PROJECT,
                                  hProject,
                                  0);
                eplSetParam(session,
                                  hCmd,
                                  EPL_PARAM_PROJECTDATA_CREATE_SYMFILE,
                                  "plugs",
                                  0);
                eplSetParam(session,
                                  hCmd,
                                  EPL_PARAM_PROJECTDATA_CREATE_SYMNR,
                                  "1",
                                  0);
                eplSetParam(session,
                                  hCmd,
                                  EPL_PARAM_PROJECTDATA_CREATE_SYMVAR,
                                  "0",
                                  0);

                //Execute command
                if(eplExecuteCommand(session, hCmd) == EPL_OK)
                {
                        // Query result:
                        hRet = eplGetHandleParam(session,
                                            hCmd,
                                            EPL_PARAM_PROJECTDATA_CREATE_RESULT,
                                            0);
                        if(hRet != EPL_ERROR)
                                hRet = eplCloneHandle(session, hCmd);
                }
                eplCloseObject(session, hCmd);
        }
        return hRet;
}

Reference