This document explains how clients built with the COBOL Wrapper use explicit broker logon and logoff functions.

It is assumed that you are familiar with the concepts of explicit and implicit broker logon. 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 The RPC Communication Area (Reference)

To log on to the Broker

1. Log on to the broker with the function Logon LO provided by the generic RPC services module.

   In the scenarios Micro Focus, Batch, CICS and IMS with the Call Interface:

   ...
   * Broker Logon
    MOVE "2000" TO COMM-VERSION.
    MOVE "LO"   TO COMM-FUNCTION.
   * Set broker user ID in RPC Communication Area
    MOVE "COB-USER"  TO COMM-ETB-USER-ID.
   *  Call the broker
    CALL "COBSRVI" USING ERX-COMMUNICATION-AREA
    ON EXCEPTION
    ...
    NOT ON EXCEPTION
    ...
    END-CALL.
   * begin of application logic
    ...

   Or:
   In the scenario Using the COBOL Wrapper for CICS with DFHCOMMAREA Calling Convention (z/OS and z/VSE) with the EXEC CICS LINK Interface:

   ...
   * Broker Logon
    MOVE "2000" TO COMM-VERSION.
    MOVE "LO"   TO COMM-FUNCTION.
   * Set broker user ID in RPC Communication Area
    MOVE "COB-USER"  TO COMM-ETB-USER-ID.
   * Call the 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
       END-IF
    ELSE
   *    Perform error-handling
    END-IF.
   * begin of application logic
   ...

2. Issue your RPC requests as without using explicit logon and logoff.

Notes:

1. The logon call is the first call to the broker, before any RPC call.
2. 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.
3. If EntireX Security is to be used, see Using the COBOL Wrapper with EntireX Security.

To log off from the Broker

• Log off from the broker with the function Logoff LF provided by the generic RPC services module with the Call Interface

  ...
  * end of application logic including calls to generated interface objects
  * Broker Logoff
   MOVE "2000" TO COMM-VERSION.
   MOVE "LF"   TO COMM-FUNCTION.
  * Call the broker
   CALL "COBSRVI" USING ERX-COMMUNICATION-AREA
   ON EXCEPTION
   . . .
   NOT ON EXCEPTION
   . . .
   END-CALL.
   ...

  Or:
  with the EXEC CICS LINK interface (see Logon above).

The logoff call should be issued as soon as RPC communication is no longer needed.