Concepts: Command

The EPLAN 21 API contains only a very limited number of functions. In order not to have to write an individual API function for each EPLAN 21 functionality, the concept of commands has been developed. This concept allows for calling up any EPLAN 21 functions via a unique interface.

Commands are objects which make the EPLAN 21 functionalities available to the developer. Like all other EPLAN 21 objects, commands are referenced via handles. Each command has a unique name by which it can be created. Most commands expect one or several parameters or return values after execution.

In addition to the functions for generating, parameterizing, and executing commands, there is the possibility to dynamically provide the system with further commands by registering a command-handler function. These newly registered commands are available via the API (like all other commands) and can be used in other AddIns.

The eplRegisterCommandHandler function registers a command handler. If a command is registered under an already existing name, the existing command is replaced. The Commands reference provides an overview of all implemented commands.

All commands must be completely parameterized before being executed. As a command is possibly executed in an open transaction, no user interaction may take place meanwhile. In order to allow for progress information, updates of views (e.g. dialogs), etc., the commands can send notifications during their execution.

EPLAN commands write their error messages into an error log (see Error Treatment).

The following example shows how a command is used to open an existing EPLAN 21 database. The example is taken from the documentation of the EPLAN.EPLAN21.DATABASE.OPEN command.

Example

EplHandle
openDbTestFunc(EplHandle s)  //The session s must be transferred to the function

{
        EplHandle ret;

        // Create command:
        EplHandle dbCommand =
                eplCreateCommand(s, L"EPLAN.EPLAN21.DATABASE.OPEN");

        // Could the command be created?
        if(dbCommand != EPL_ERROR)
        {
                // Set database name:
                eplSetParam(
                        s,
                        dbCommand,
                        EPL_PARAM_OPENDB_DBNAME,
                        L"c:\\tmp\\test.db"
                        0);
                ret = eplExecuteCommand(s, dbCommand);
                if(ret != EPL_ERROR)		// if DATABASE.OPEN is executed successfully
	    {					// the function is to return the database handle 
	               ret = eplGetHandleParam(
				s,
				dbCommand,
				EPL_PARAM_OPENDB_DBHANDLE,
				0);
	     }		

        } else {
                /* Error treatment
                   ...
                 */
                ret = EPL_ERROR;
        }

        eplCloseObject(dbCommand);

        return ret;
}