Using Broker Logon and Logoff

Broker logon and logoff functions are provided through the Generic RPC Services module. See Using the Generic RPC Services Module.

The following topics are covered here:

Log on to the Broker
Log off from the Broker
Additional Hints

Log on to the Broker

With the Call Interface

...
ERXCOM.COM_FUNCTION = 'LO'; /* Broker Logon */
ERXCOM.COM_CLIENT_USERID   = 'PLI-USER';
ERXCOM.COM_CLIENT_PASSWORD = 'PLI-PASS';
call xxxSRVI(ERXCOM); /* see (1) below */
IF SUBSTR(ERXCOM.COM_ERROR,8) ^= ERX_S_SUCCESS then
DO;
/* error handling */
/* ... */
END;
/* begin of application logic including calls to interface objects */
...

With the EXEC CICS LINKInterface

...
ERXCOM.COM_FUNCTION = 'LO'; /* Broker Logon */
ERXCOM.COM_CLIENT_USERID   = 'PLI-USER';
ERXCOM.COM_CLIENT_PASSWORD = 'PLI-PASS';
CICS_LEN = STORAGE(ERXCOM);
CICS_RESP1 = DFHRESP(NORMAL);
CICS_RESP2 = DFHRESP(NORMAL);
/* called CICS program name depends on PP switch ERXFCTPRE */
EXEC CICS LINK PROGRAM  ('xxxSRVI') /* see (1) below */
               RESP     (CICS_RESP1)
               RESP2    (CICS_RESP2)
               COMMAREA (ERXCOM)
               LENGTH   (CICS_LEN);
IF SUBSTR(ERXCOM.COM_ERROR,8) ^= ERX_S_SUCCESS then
DO;
/* error handling */
/* ... */
END;
/* begin of application logic including calls to interface objects */
...

⁽¹⁾ The prefix of the program name (xxxSRVI) can be customized, see PL/I Preprocessor Settings. The default is PLISRVI.

Log off from the Broker

With the Call Interface

...
/* end of application logic including calls to interface objects */
ERXCOM.COM_FUNCTION  = 'LF'; /* Broker Logoff */
call xxxSRVI(ERXCOM); /* see (1) below */
IF SUBSTR(ERXCOM.COM_ERROR,8) ^= ERX_S_SUCCESS then
DO;
/* error handling */
/* ... */
END;
...

(1) The prefix of the program name (xxxSRVI) can be customized, see PL/I Preprocessor Settings. The default is PLISRVI.

With the EXEC CICS LINKInterface

See Log on to the Broker above.

Additional Hints

The COM_CLIENT_USERID field (and the COM_CLIENT_TOKEN field, when provided) must not change from logon, during call of interface objects, until final logoff.
If Explicit Logon is used, as demonstrated here, the COM_CLIENT_PASSWORD field may only be provided for the broker logon function call.
The logon call is the first call to the broker, before any application logic including calls the client interface object. The logoff call should be issued as soon as RPC communication is no longer needed.
It is also possible to work with Implicit Logon.
Whenever possible we recommend using Explicit Logon as demonstrated here.