Offline Applications

Programming Offline Applications

The EPLAN 21 API can also be used by independent programs. You can access EPLAN 21 as module from a program that runs separately. In this case, the EPLAN 21 DLLs are used without having to start EPLAN 21 directly. Such programs can use all commands that do not require a running version of EPLAN (e.g. EPLAN.EPLAN21.ADDIN.REGISTER cannot be used). In order to be able to correctly initialize EPLAN 21, such "offline programs" must only call up the API functions eplInitialize and eplDeinitialize when the program is started or ended.

If an API program works as an AddIn, a transaction to the database is constantly kept open by EPLAN 21. This does not apply to an offline program. Each function or each command that accesses the database opens and closes its own transaction. This results in performance loss. We therefore recommend to embed the offline program in a transaction by using the functions eplStartTransaction (0) and eplCommitTransaction (see example).

General Explanations

The EPLAN 21 API uses UNICODE characters for all strings instead of the "normal" ANSI characters. A UNICODE string can be recognized by the "L", which is put in front of the string (or in front of a single character):
L"This is a UNICODE string"
L'A'
A UNICODE character is of the wchar_t type instead of the char type and corresponds to unsigned short. To edit strings, you have the functions wcscmp, wcscpy, wtoi, _itow, ...(wcs stands for "wide character string") at your disposal, similarly to the string functions strcmp, strcpy, atoi, _itoa, ..., that are already known.

Example

#include "stdafx.h"
#include "EplanApi.h"        // The header file must be set as "include".
                             // For this, the include path must be known to the development environment.

int main(int argc, char* argv[])
{
        int ret = false;
        const int BUFLEN = 100;
        wchar_t          buf[BUFLEN];

        // The error messages, which can return the individual functions,
        // are ignored here for reasons of clarity. However, in general, they 
        // should be tested!

        // Initialize Eplan
        eplInitialize();
        eplStartTransaction (0);

        // Create a session: A session can be understood as a container for handles.
        EplHandle hSession;
        hSession = eplCreateSession();

        // In each offline program the licensing command has to be
        // executed at the beginning (after the session has been created).

        // Create licensing command
    EplHandle hcmdLicense = eplCreateCommand(hSession, L"EPLAN.EPLAN21.LICENSE");

    // Set licensing key

    eplSetParam(hSession, hcmdLicense, EPL_PARAM_LICENSE_USERNAME, "IHR_LIZENZNAME", 0);
    eplSetParam(hSession, hcmdLicense, EPL_PARAM_LICENSE_USERNUMBER, "1234567890ABC", 0);

    // Execute licensing command
    eplExecuteCommand(hSession, hcmdLicense);

        // The user group is selected and set depending on the rights the application 
        // must have for changing EPLAN 21 databases. In our example we choose
        // the "EPLAN 21 administrator". For this, we use the EPLAN.EPLAN21.LOGIN
        // command.

        // The command for changing the user group does not require a user group 
        // name but an internal user group ID. To find this ID for a description
        // --in case you do not want to look up the ID in the documentation--
        // proceed as follows:
        // Open an iterator in all user groups that exist in EPLAN.
        // Each user group included in the iterator is asked for its name. If this
        // name corresponds to the desired one, the user group is asked for its
        // ID and the "...LOGIN" command is parametrized with this ID
        // and the password.

        // Open the iterator (parent is ignored):
        EplHandle hiterRole = eplOpenIterator(hSession, -1, EPL_ITERTYPE_ROLES);

        // Get the handle of the first user group:
        EplHandle hRole = eplFirst(hSession, hiterRole);

        // As long as there are user groups, "hRole" != EPL_ERROR: 
        while(hRole != EPL_ERROR)
        {
                // Query the name of the user group
                eplGetProperty(hSession, hRole, EPL_PROPERTY_GENE_NAME, 0, buf, BUFLEN);

                // Name == EPLAN 21 administrator
                // CAUTION: The user group depends on the
                // language in which EPLAN 21 has been installed.
                if(wcscmp(buf, L"EPLAN 21-Administrator") == 0)
                {
                        // Query the ID of the user group
                        eplGetProperty(hSession, hRole, EPL_PROPERTY_ROLE_ID, 0, buf, BUFLEN);

                        // Now all parameters for the LOGIN are known:
                        EplHandle hcmdLogin = eplCreateCommand(hSession, L"EPLAN.EPLAN21.LOGIN");
                        eplSetParam(hSession, hcmdLogin, EPL_PROPERTY_PARAM_LOGIN_ROLEID, buf, 0);
                        eplSetParam(hSession, hcmdLogin, EPL_PROPERTY_PARAM_LOGIN_PASSWORD, password, 0);
                        ret = eplExecuteCommand(hSession, hcmdLogin);
                        eplCloseObject(hSession, hiterRole);

                        // Terminate while loop
                        break;
                }
                // Get the next user group from the iterator: 
                hRole = eplNext(hSession, hiterRole);
        }
        // Close the iterator
        eplCloseObject(hsession, hiterRole);
        // To avoid memory leaks release objects that are no longer required
        eplCloseObject(hsession, hcmdLogin);

        // Now you can open a database

        // Generate a command for opening the database:
        EplHandle hcmdDBopen = eplCreateCommand(hSession, L"WUP.EPLAN21.DATABASE.OPEN");

        // Set the parameter DBNAME:
        eplSetParam(hSession, hcmdDBopen, EPL_PROPERTY_PARAM_OPENDB_DBNAME, L"NAME_IHRER_DATENBANK", 0);

        // eplExecuteCommand returns EPL_ERROR if the command failed
        // and the database could not be opened. In this case the error log  
        // of the command or the global error log could be asked for the 
        // concrete error (-> eplGetLastError())

        ret = eplExecuteCommand(hSession, hcmdDBopen);

        // Release command object:
        eplCloseObject(hSession, hcmdDBopend);

        // After this, we navigate through the data model
        // Database -> projects -> pages -> instances -> instance properties

        // Iterator for all projects of the database:
        EplHandle hiterPrj = eplOpenIterator(hSession, -1, EPL_ITERTYPE_PROJECTS);
        EplHandle hPrj = eplFirst(hSession, hiterPrj);
        while(hPrj != EPL_ERROR)
        {
                // For each project for all pages of the project: 
                EplHandle hiterPag = eplOpenIterator(hSession, hPrj, EPL_ITERTYPE_PAGES);
                EplHandle hPag = eplFirst(hSession, hiterPag);
                while(hPag != EPL_ERROR)
                {
                        // For each page for all instances of the page: 
                        EplHandle hiterInst = eplOpenIterator(hSession, hPag, EPL_ITERTYPE_INSTANCES);
                        EplHandle hInst = eplFirst(hSession, hiterInst);
                        while(hInst != EPL_ERROR)
                        {
                                // Get the name of the page
                                eplGetProperty(hSession, hInst, EPL_PROPERTY_GENE_NAME, 0, buf, BUFLEN);

                                //...
                                //...
                                //...
                                //...

                                hInst = eplNext(hSession, hiterInst);
                        }
                        eplCloseObject(hSession, hiterInst);
                        hPag = eplNext(hSession, hiterPag);
                }
                eplCloseObject(hSession, hiterPag);
                hPrj = eplNext(hSession, hiterPrj);
        }
        eplCloseObject(hSession, hiterPrj);

        // Generate a command for closing the database
        EplHandle hcmdDBclose = eplCreateCommand(hSession, L"EPLAN.EPLAN21.DATABASE.CLOSE");
        // and execute it...
        ret = eplExecuteCommand(hSession, hcmdDBclose);
        // Close command object
        eplCloseObject(hSession, hcmdDBclose);


        // Close the session. Since all objects of a session are automatically 
        // released when the session is closed, you could also do without 
        // eplCloseObject mentioned above.

        eplDestroySession(hSession);
        eplCommitTransaction;

        // Finally EPLAN is deinitialized. 
        eplDeinitialize();

        return 0;
}