EPLAN.EPLAN21.OBJECT.DELETE

Contents

Description

This command deletes all objects that are transferred in the EPL_PARAM_OBJECT_DELETE parameter.

Parameters

All parameters have the prefix "EPL_PARAM_OBJECT_DELETE_".

ParameterID Type Description
OBJECTS [IN]
EplHandle

Handle of the iterator that contains the objects to be deleted. The iterator may contain only objects of one type (for example, only pages or only projects).

At the moment this command can only delete the following objects:
  • EPL_OBJECTTYPE_MACRO
  • EPL_OBJECTTYPE_PROJECT
  • EPL_OBJECTTYPE_PAGE
  • EPL_OBJECTTYPE_FORM
  • EPL_OBJECTTYPE_PLOTFRAME
  • EPL_OBJECTTYPE_SYMBOLFILE
  • EPL_OBJECTTYPE_INSTANCE
  • EPL_OBJECTTYPE_DEVICETAG
  • EPL_OBJECTTYPE_NETWIRE

  • Only active when the "network-based wires" mode is active in the project.
NET [IN, OPTIONAL]
EplHandle

Optional handle of the network from which NetWire(s) are removed and deleted. By using this handle NetWires can be deleted more quickly.

NETPROJECT [IN]
EplHandle

Handle of the project from which NetWires are deleted. At present the parameter is exclusively used to delete NetWires.

REMOVEEMPTY_DEVICES [IN, OPTIONAL]
String

This flag is only active when pages are deleted. When pages are deleted empty devices may arise. If the parameter is set to "1" these empty devices will also be deleted.

DELETEMODE [IN, OPTIONAL]
String

This flag is only active when instances are deleted. The delete mode configured in the graphical editor can here be temporarily converted. If this parameter is empty the delete mode of the graphical editor is used.
The flag can assume the following values:
"0" corresponds to "Only instance"
"1" corresponds to "Delete completely"
"2" corresponds to "Except for cross-references"
. All other values will be ignored.

Note:

When deleting the following object types please note:

  • EPL_OBJECTTYPE_PAGE

  • Using the EPL_PARAM_OBJECT_DELETE_REMOVEEMPTY_DEVICES flag you can control whether the resulting empty devices are also to be deleted.
    When deleting pages the set delete mode is not considered, i.e. the components are not booked back but deleted completely.
    Before starting to delete pages all editors and dialogs belonging to the same project should be closed.
    The last page of a macro or a project cannot be deleted; in this case the error code EPL_ERR_INVALID_ARGUMENT will be returned.

  • EPL_OBJECTTYPE_FORM, EPL_OBJECTTYPE_PLOTFRAME, EPL_OBJECTTYPE_SYMBOLFILE

  • Master data can only be deleted when they are not used any more. For instance, symbol files cannot be deleted if projects are still existing in the open databases using these symbol files.

  • EPL_OBJECTTYPE_INSTANCE

  • The instances to be deleted must all be located on the same page.
    The delete mode can be set via the parameter EPL_PARAM_OBJECT_DELETE_DELETEMODE.
    Instances on write-protected levels cannot be deleted. These non-deleted instances are inserted in the iterator (parameter EPL_PARAM_OBJECT_DELETE_OBJECTS). All other deleted instances are removed from the iterator.

  • EPL_OBJECTTYPE_DEVICETAG

  • The devices to be deleted must be located in the same project.
    A device can only be deleted if it does not include any components any longer.
    It is not possible to delete devices from terminals, they are deleted automatically.
    When devices are deleted no graphical editor for a page of this project must be open.

    Error Messages

    The eplExecuteCommand function returns EPL_OK if the objects were deleted 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 selected objects.
    EPL_ERR_INVALID_ARGUMENT No iterator has been transferred, or the deleting of the contained objects has not been supported yet. If instances are to be deleted, these may possibly not be on the same page as is required.
    EPL_ERR_OBJECT_DELETE_NO_ACCESS You tried to delete objects that are not available in Write access.
    EPL_ERR_OBJECT_DELETE_UNDO_LIST_OPEN When pages and devices are deleted no undo list must exist for the project in which the pages or devices are located. An undo list typically refers to the open graphical editor.
    EPL_ERR_OBJECT_DELETE_DEVICE_NOT_SAME_CIRCUIT The transferred devices are not located in the same project.
    EPL_ERR_OBJECT_DELETE_TERMINALDEVICE_DETECTED This error occurs when the attempt was made to delete the device of a terminal directly. The device of a terminal is automatically deleted as well when a terminal is deleted.
    EPL_ERR_OBJECT_DELETE_IS_USED An object cannot be deleted as it is still being used. This error may occur if a device is to be deleted which still contains components or if master data are to be deleted which are still in use.

    Example

    The following example shows a function that uses this command.

    EplHandle
    deletePages(EplSession hSession, EplHandle hPageIter)
    {
            EplHandle hRet(EPL_ERROR);
    
            EplHandle hCmd = eplCreateCommand(hSession, L"EPLAN.EPLAN21.OBJECT.DELETE");
    
            if(hCmd != EPL_ERROR)
            {
                    eplSetHandleParam(hSession, hCmd, EPL_PARAM_OBJECT_DELETE_OBJECTS, hPageIter, 0);
    
                    hRet = eplExecuteCommand(hSession, hCmd);
                    eplCloseObject(hSession, hCmd);
            }
    
            return hRet;
    }
    

    Reference