EPLAN.EPLAN21.GROUP.CREATE

Contents

Description

Instances can be grouped with this command.
If some of the transferred instances have already been grouped, these groups are entirely imported as subgroups into the new group. If only one instance is already in another group, all instances of this group are transferred to the new group.

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

Parameters

All parameters have the prefix "EPL_PARAM_GROUP_CREATE_"!

ParameterID Type Description
OBJECTS [IN]
EplHandle
Handle to the iterator that contains the instances to be grouped. The instances must be located on one page!
PAGE [IN]
EplHandle
Handle of the page on which the instances are located and on which the group is created.
RESULT [OUT]
EplHandle
Handle of the created group.

Error Messages

The eplExecuteCommand function returns EPL_OK if the new group 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 page.
EPL_ERR_FAILED The group could not be created.
EPL_ERR_INVALID_ARGUMENT An invalid object was transferred or the instances are not located on one page.
EPL_ERR_NOT_ENOUGH_ELEMENTS At least two objects must be transferred to create a group.

Example

The following example shows a function that uses this command.

EplHandle
createGroup(EplSession hSession, EplHandle hPage, EplHandle hInstanceIter)
{
        EplHandle hRet(EPL_ERROR);

        EplHandle hCmd = eplCreateCommand(hSession, L"EPLAN.EPLAN21.GROUP.CREATE");

        if(hCmd != EPL_ERROR)
        {
                eplSetHandleParam(hSession, hCmd, EPL_PARAM_GROUP_CREATE_PAGE, hPage, 0);
                eplSetHandleParam(hSession, hCmd, EPL_PARAM_GROUP_CREATE_OBJECTS, hPage, 0);

                hRet = eplExecuteCommand(hSession, hCmd);
                if(hRet != EPL_ERROR)
                {
                        hRet = eplGetHandleParam(hSession, hCmd, EPL_PARAM_GROUP_CREATE_RESULT);

                        hRet = eplCloneHandle(hSession, hRet);
                }

                eplCloseObject(hSession, hCmd);
        }

        return hRet;
}

Reference