Using Broker Logon and Logoff

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:

Start of instruction setTo 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.

Start of instruction setTo 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.