Using Broker Logon and Logoff

This document covers the following topics:

Introduction

This section explains how clients built with the COBOL Wrapper use explicit broker logon and logoff functions. The logon call is the first call to the broker, before any RPC call. The COMM-ETB-USER-ID field (and the COMM-ETB-TOKEN field, where provided) must not change from logon, through all calls of client interface objects, until final logoff. The logoff call should be issued as soon as RPC communication is no longer needed. This is similar to LOGONand LOGOFF, USER-ID and TOKEN and Authentication under Writing Applications using EntireX Security in the ACI Programming documentation.

To use explicit broker logon and logoff you need the following components:

  • the Delivered Modules are provided to log on to and log off from the broker

  • the copybook ERXCOMM if a 32-byte broker password is sufficient; see RPC communication area Copybook ERXCOMM

  • the copybook ERXVSTR to use a long broker password; see RPC communication area Copybook ERXVSTR

  • We strongly recommend using SSL/TLS if you send an authentication as described here with the COBOL Wrapper to a secure partner. See also SSL/TLS Parameters for SSL Clients under SSL/TLS, HTTP(S), and Certificates with EntireX in the platform-independent Administration documentation.

Logging on Using Short Broker Passwords (all Interface Types)

This approach allows a maximum of 32 bytes for the broker password. The code you write depends on the interface type:

See Client Interface Types.

Call Interface

This interface type applies to the scenarios CICS | Batch | IMS.

Start of instruction setTo log on to the Broker with a short password

  1. Declare and initialize the RPC communication area as described under Only Copybook ERXCOMM is Used under Step 1: Declare and Initialize the RPC Communication Area in section Writing Standard Call Interface Clients.

  2. Log on to the broker with the logon function LO provided by the generic RPC services module, using the Call Interface. 

    * Set function broker logon
 MOVE "LO"   TO COMM-FUNCTION.
* Set broker user ID in RPC Communication Area
 MOVE "COB-USER" TO COMM-ETB-USER-ID.

* Optionally set broker password/kernelsecurity to use EntireX Security
 MOVE "COB-PASS" TO COMM-ETB-PASSWORD.
 MOVE "Y"        TO COMM-KERNEL-SECURITY.

* Call generic RPC service module to call broker (see Note 1)
 CALL "COBSRVI" USING ERX-COMMUNICATION-AREA
 ON EXCEPTION
*   Perform error-handling
 NOT ON EXCEPTION
    IF (COMM-RETURN-CODE = 0) THEN
*       Perform success-handling
    ELSE
*       Perform error-handling (see Note 2)
    END-IF
 END-CALL.
* begin of application logic
 ...

  3. Issue your RPC requests as usual, without using explicit logon and logoff.

Start of instruction setTo log off from the Broker with a short password

  • Log off from the broker with the log off function LF provided by the generic RPC services module, using a CALL statement.

EXEC CICS LINK Interface

This interface type applies to the scenario Using the COBOL Wrapper for CICS with DFHCOMMAREA Calling Convention (z/OS and z/VSE).

Start of instruction setTo log on to the Broker with a short password

  1. Declare the RPC communication area as described under Step 1: Declare IDL Structures and RPC Communication Area in section Writing EXEC CICS LINK Clients.

  2. Initialize the RPC communication area as described under Step 2: Initialize the RPC Communication Area under Writing EXEC CICS LINK Clients.

  3. Log on to the broker with the logon function LO provided by the generic RPC services module, using EXEC CICS LINK. 

      . . .
 MOVE "LO"   TO COMM-FUNCTION.
* Set broker user ID in RPC Communication Area
 MOVE "COB-USER" TO COMM-ETB-USER-ID.

* Optionally set broker password/kernelsecurity to use EntireX Security
 MOVE "COB-PASS" TO COMM-ETB-PASSWORD.
 MOVE "Y"        TO COMM-KERNEL-SECURITY.

* Call generic RPC service module to call broker
 EXEC CICS LINK PROGRAM  ("COBSRVI")
                RESP     (CICS-RESP1)
                RESP2    (CICS-RESP2)
                COMMAREA (ERX-COMMUNICATION-AREA)
                LENGTH   (LENGTH OF ERX-COMMUNICATION-AREA)
 END-EXEC.
 IF WORKRESP = DFHRESP(NORMAL)
    IF (COMM-RETURN-CODE = 0) THEN
*       Perform success-handling
    ELSE
*       Perform error-handling (see Note 2)
    END-IF
 ELSE
*    Perform error-handling
 END-IF.
* begin of application logic
...

  4. Issue your RPC requests as usual, without using explicit logon and logoff.

Start of instruction setTo log off from the Broker with a short password

  • Log off from the broker with the log off function LF provided by the generic RPC services module, using EXEC CICS LINK.

Notes:

  1. If you are only using copybook ERXCOMM only, pass only the address of ERXCOMM to the generic RPC service module.
  2. The field COMM-RETURN-CODE in the RPC communication area contains the error provided by the COBOL Wrapper. For the error messages returned, see Error Messages and Codes.

Logging on Using Long Broker Passwords (z/OS with Call Interface)

This section applies to the scenarios CICS, Batch and IMS with the CALL interface.

With this approach you can use long passwords. It requires the ERXVSTR copybook.

The RPC communication area extension copybook ERXVSTR is generated for Target Operating System z/OS and RPC clients using a call interface to its client interface object, meaning one of the following Client Interface Types is selected:

Start of instruction setTo log on to the Broker with a long password

  1. Declare and initialize the RPC communication area as described under Both Copybooks ERXCOMM and ERXVSTR are Used under Step 1: Declare and Initialize the RPC Communication Area in section Writing Standard Call Interface Clients.

  2. Log on to the broker with the logon function LO provided by the generic RPC services module, using the Call Interface. 

    * Set function broker logon
 MOVE "LO"   TO COMM-FUNCTION.
* Set broker user ID/kernelsecurity in RPC Communication Area
 MOVE "COB-USER" TO COMM-ETB-USER-ID.
 MOVE "Y"        TO COMM-KERNEL-SECURITY.
* set long broker password in RPC Variable String Area
 INSPECT ETBPWD TALLYING STR-LENGTH FOR CHARACTERS BEFORE SPACE.
 MOVE 1 TO STR-OFFSET.
 MOVE STR-OFFSET TO COMM-ETB-PASSWORD-OFFSET.
 MOVE STR-LENGTH TO COMM-ETB-PASSWORD-LENGTH.
 STRING ETBPWD DELIMITED BY SPACE INTO 
          COMM-STRING-AREA WITH POINTER STR-OFFSET.
* Call generic RPC service module to call broker
  CALL "COBSRVI" USING ERX-COMMUNICATION-AREA
                       ERX-COMMUNICATION-VSTR.
 ON EXCEPTION
*       Perform error-handling
 NOT ON EXCEPTION
     IF (COMM-RETURN-CODE = 0) THEN
*       Perform success-handling
    ELSE
*       Perform error-handling (see Note 2)
    END-IF
 END-CALL.
  . . .

Start of instruction setTo log off from the Broker with a long password

  • See the following code snippet:

      . . .
* Set function broker logoff 
 MOVE "LF"   TO COMM-FUNCTION.
* Set broker user ID in RPC Communication Area
 MOVE "COB-USER" TO COMM-ETB-USER-ID.
* Call generic RPC service module to call broker  (see Note 1)
 CALL "COBSRVI" USING ERX-COMMUNICATION-AREA
                      ERX-COMMUNICATION-VSTR.
 ON EXCEPTION
*   Perform error-handling
 NOT ON EXCEPTION
    IF (COMM-RETURN-CODE = 0) THEN
*      Perform success-handling
    ELSE
*      Perform error-handling (see Note 2)
    END-IF
 END-CALL.
  . . .

Notes:

  1. If both copybooks are used, you need to pass both addresses, first the address of ERXCOMM, then the address of ERXVSTR to the generic RPC service module.
  2. The field COMM-RETURN-CODE in the RPC communication area contains the error provided by the COBOL Wrapper. For the error messages returned, see Error Messages and Codes.