Opening a Process

The jomSignOn call, shown in the following example, initializes a process in the current node.

int jomSignOn(const DskHandle *pNodeHandle,
              DskHandle       *pProcessHandle,
              DskHandle       *pSecurityHandle,
              DskParam        *pSchemaName,
              DskParam        *pAppName,
              DskParam        *pUserName,
              DskParam        *pPassword,
              const DskParam  *pDbMode,
              const DskParam  *pDbUsage,
              UInt32          lineNo)

This call starts an application process in the specified subschema and creates the required application and process objects.

The jomSignOn API call must be called to start each new application, which has an associated JADE process.

If the requested mode or usage conflicts with the current mode or usage of the database by existing users, the request fails and an exception is raised.

For user validation, the jomSignOn call operates in the following modes.

1. A user code (and optional password) is supplied. The JADE Object Manager directly invokes the isUserValid method on the schema Global instance, passing the userName and password properties received from the jomSignOn API call.

2. No user code is supplied (null parameter). The JADE Object Manager invokes the getAndValidateUser method on the schema global instance. If this succeeds, it then invokes the isUserValid method on the schema global instance, passing the userCode and password properties returned by the user method. (For more details, see "Global Class", in Chapter 1 of the JADE Encyclopaedia of Classes.)

JADE applications controlled by the JADE application controller (jade.exe) use the second mode; that is, no user code is supplied. Non–JADE applications can choose between either mode, but they would normally use the first mode; that is, a user code and optional password are supplied. The JADE ODBC interface uses the first mode.

The address of a null-valued security handle must be passed on the first call to the jomSignOn API call.

The security handle returned in the pSecurityHandle parameter following a successful sign-on call can be used in subsequent jomSignOn calls by the application controller or by other JADE tools, to avoid the need for users to log on multiple times when starting multiple applications in a session.

If the security handle is valid for the node and subschema combination, the JADE Object Manager permits the sign-on without invoking the user validation methods. A specified security handle is valid only for the subschema for which it was first obtained. (For more details, see "User-Validation Support", in Chapter 2.)

When an application is terminated, the application controller (or other tool) should make a jomSignOff API call to terminate the JADE process. A process (Windows thread) can call this API once only, unless a call to the jomSignOff API call is issued. (For details about the jomSignOff call, see "Closing a Process", later in this chapter.)

The code in the following example uses the C++ API to start an application process. (If you use the code in this example, make sure that you change variable values so that they are appropriate for your system.)

DskParam dbUsageParam;
paramSetInteger(dbUsageParam, DB_UPDATE);
DskParam dbModeParam;
paramSetInteger(dbModeParam, DB_SHARED);

DskParam schemaNameParam;
paramSetCString(schemaNameParam, "<schemaName>");
DskParam appNameParam;
paramSetCString(appNameParam, "<applicationName>");
DskParam userParam;
paramSetCString(userParam, "<myUser>");
DskParam passwordParam;
paramSetCString(passwordParam, TEXT(""));

// sign on to the database - once per process/thread
// note that nodeHandle was passed to the call to jomInitialize()
DskHandle dbHandle;
DskHandle securityHandle = { 0 };
result = ::jomSignOn(&nodeHandle, &dbHandle, &securityHandle, &schemaNameParam, &appNameParam,
&userParam, &passwordParam, &dbModeParam, &dbUsageParam, __LINE__);
CHECK_RESULT;

The parameters for this call are described in the following subsections.