EPLAN.EPLAN21.DATABASE.OPEN_SLAVE

Contents

Description

Command for opening an existing EPLAN 21 subdatabase and connecting it to an already open working set.

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

Parameters

All parameters have the prefix "EPL_PARAM_DATABASE_OPEN_SLAVE_".

ParameterID Type Description
DBNAME [IN]
String

Name of the subdatabase to be opened.

MASTERDBHANDLE [IN]
EplHandle

Handle to the already open main database.
The main database identifies the working set with which the subdatabase to be opened is to be connected.

DBFLAG [IN, OPTIONAL]
Boolean

Read-only flag for the subdatabases.

1: Databases are opened read-only.
0: Databases are opened read-write (default).

Note: Databases should always be opened in the read-only mode and then be locked for editing it with the EPLAN.EPLAN21.DATABASE.LOCK command in exclusive use.

FORCELINK [IN, OPTIONAL]
Boolean

Forcing connection to working set.

1: Force connection to working set.
0: Do not force connection to working set (default).

If this flag is set, a subdatabase opened read-write will always be connected to the current working set with the original connection being interrupted.
Use this flag only as an exception: Generally, subdatabases should be removed from a working set and be closed via the "EPLAN.EPLAN21.DATABASE.CLOSE_SLAVE" command before being reopened and connected to another working set via the "EPLAN.EPLAN21.DATABASE.OPEN_SLAVE" command.
If the original working set is no longer available, a subdatabase cannot be removed from a working set by using this method. You have to use the FORCELINK parameter to assign a subdatabase to a new working set.

Error Messages

The eplExecuteCommand function returns EPL_OK if the subdatabase was opened and could be added to the working set.

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_INVALID_ARGUMENT The name of the subdatabase was empty.
EPL_ERR_DATABASE_OPEN_SLAVE_INVALID_MASTER The handle to the main database is invalid.
EPL_ERR_DATABASE_OPEN_SLAVE_DB_NOT_FOUND The subdatabase could not be found.
EPL_ERR_DATABASE_OPEN_SLAVE_DB_ALREADY_OPEN The subdatabase is already open and connected with the transferred main database.
EPL_ERR_DATABASE_OPEN_SLAVE_DB_CONVERSION_FAILED The subdatabase could not be converted.
EPL_ERR_DATABASE_OPEN_SLAVE_DB_TYPEMISMATCH Wrong database type (macro database as resource database or something similar).
EPL_ERR_DATABASE_OPEN_SLAVE_DB_WRONG_MODE Wrong mode (e.g. if the resource database is specified without using separate databases).
EPL_ERR_DATABASE_OPEN_SLAVE_WRONGMASTER The subdatabase does not belong to the transferred working set.
See also description of the FORCELINK parameter.
EPL_ERR_DATABASE_OPEN_SLAVE_DB_MASTERNOTOPEN Error cannot occur!
EPL_ERR_DATABASE_OPEN_SLAVE_MASTERNOTLOCKED The subdatabase does not belong to a working set yet, and is therefore automatically connected to the transferred working set; or the FORCELINK parameter is set and a connection to the transferred working set is forced. This connection cannot be established, since the main database is not locked for exclusive use.

Example

The following example shows a function that opens a working set. Afterwards, a subdatabase is opened and added to the working set.

EplHandle
openSlaveDbTestFunc(EplSession s)
{
        EplHandle ret;
         
        // Create command for opening a working set:
        EplHandle openDbCommand = eplCreateCommand(
		s, "EPLAN.EPLAN21.DATABASE.OPEN");

        if(openDbCommand != EPL_ERROR)
        {
                // Set main database name:
                eplSetParam(
                        s,
                        openDbCommand,
                        EPL_PARAM_OPENDB_DBNAME,
                        L"c:\\tmp\\test.db"
                        0);

                ret = eplExecuteCommand(s, openDbCommand);

		if(ret != EPL_ERROR)
		{
			// Get handle of main database
			EplHandle masterDbHandle = eplGetHandleParam(
				s,
				openDbCommand,
				EPL_PARAM_OPENDB_DBHANDLE,
				0);

			if(masterDbHandle != EPL_ERROR)
			{
				// Create command for opening
				// a subdatabase:
				EplHandle openSlaveCommand = eplCreateCommand(
						s, "EPLAN.EPLAN21.DATABASE.OPEN_SLAVE");

				// Could the command be created?
				if(openSlaveCommand != EPL_ERROR)
				{
					// Set database name:
					eplSetParam(
						s,
						openSlaveCommand,
						EPL_PARAM_DATABASE_OPEN_SLAVE_DBNAME,
						L"c:\\tmp\\test_slave.db"
						0);

					// Set handle of main database
					eplSetParamHandle(
						s,
						openSlaveCommand,
						EPL_PARAM_DATABASE_OPEN_SLAVE_MASTERDBHANDLE,
						masterDbHandle
						0);

					ret = eplExecuteCommand(s, openSlaveCommand);
				}

				eplCloseObject(s, openSlaveCommand);
			}

			eplCloseObject(s, masterDbHandle);
		}

		eplCloseObject(s, openDbCommand);
	}

        
        return ret;
}

Reference