This document covers the following topics:

• Introduction

• RPC Authentication Using Short RPC User ID/RPC Password (all Interface Types)

• RPC Authentication Using Long RPC User ID/RPC Password (z/OS with Call Interface)

---

Introduction

This section explains how clients built with the COBOL Wrapper can communicate with the following:

• Natural RPC Servers running under Natural Security

• RPC servers running with impersonation. See Impersonation under z/OS (CICS, Batch, IMS).

• EntireX Adapter Listener with enabled Execute Service with Client Credentials, see Configuring Listeners in the EntireX Adapter documentation.

For this you will need the following components:

• the Delivered Modules which are provided to create and get a security token

• the copybook ERXCOMM if an 8-byte RPC user ID, an 8-byte RPC password and an 8 byte RPC library are sufficient. See ERXCOMM.

• the copybook ERXVSTR to use a long RPC user ID, a long RPC password and, if required, to override the IDL library with a long RPC library. See ERXVSTR.

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

RPC Authentication Using Short RPC User ID/RPC Password (all Interface Types)

This approach allows a maximum of 8 bytes for each of RPC user ID, RPC password and RPC library. The code you write depends on the interface type:

• Call Interface

• EXEC CICS LINK Interface

Call Interface

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

To use RPC authentication using short RPC user ID, RPC password and RPC library

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. Create a security token with the function Create Security Token CT provided by the generic RPC services module.

   * Set function to create security token
    MOVE "CT"   TO COMM-FUNCTION.
   * Set RPC userid and RPC password in RPC Communication Area
    MOVE "RPC-USER" TO COMM-USERID.
    MOVE "RPC-PSWD" TO COMM-PASSWORD.
   * Optional set RPC library e.g. for Natural Security
    MOVE "RPC-LIB" TO COMM-LIBRARY.
   * Call generic RPC service module to create security token (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.
    . . .

After successful return from creating the security token, the authentication fields in the RPC communication area are properly set, so they can be used in subsequent RPC requests.

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).

To use RPC authentication using short RPC user ID, RPC password and RPC library

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. Create a security token with the function Create Security Token CT provided by the generic RPC services module.

    MOVE "CT"   TO COMM-FUNCTION.
   * Set RPC userid and RPC password in RPC Communication Area
    MOVE "RPC-USER" TO COMM-USERID.
    MOVE "RPC-PSWD" TO COMM-PASSWORD.
   * Optional set RPC library e.g. for Natural Security
    MOVE "RPC-LIB" TO COMM-LIBRARY.
   * Call generic RPC service module to create security token
    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.

After successful return from creating the security token, the authentication fields in the RPC communication area are properly set, so they can be used in subsequent RPC requests.

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.

RPC Authentication Using Long RPC User ID/RPC Password (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 a long RPC user ID, RPC password and RPC library. 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:

• CICS with Standard Linkage Calling Convention

• Batch with Standard Linkage Calling Convention

• IMS BMP with Standard Linkage Calling Convention

• IMS MPP with Standard Linkage Calling Convention

To use RPC authentication with long RPC user ID, RPC password and RPC library

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. Create a security token with the function Create Security Token CT provided by the generic RPC services module.

   * Set function to create security token
    MOVE "CT"   TO COMM-FUNCTION. 
   * Set long RPC userid in RPC Variable String Area
    INSPECT RPCUID TALLYING STR-LENGTH FOR CHARACTERS BEFORE SPACE.
    MOVE 1 TO STR-OFFSET.
    MOVE STR-OFFSET TO COMM-RPC-USERID-OFFSET.
    MOVE STR-LENGTH TO COMM-RPC-USERID-LENGTH.
    STRING RPCUID DELIMITED BY SPACE INTO 
           COMM-STRING-AREA WITH POINTER STR-OFFSET.
   * Set long RPC password in RPC Variable String Area
    INSPECT RPCPWD TALLYING STR-LENGTH FOR CHARACTERS BEFORE SPACE.
    MOVE STR-OFFSET TO COMM-RPC-PASSWORD-OFFSET.
    MOVE STR-LENGTH TO COMM-RPC-PASSWORD-LENGTH.
    STRING RPCPWD DELIMITED BY SPACE INTO 
           COMM-STRING-AREA WITH POINTER STR-OFFSET.
   * Optional set long RPC library e.g. for Natural Security
    INSPECT RPCLIB TALLYING STR-LENGTH FOR CHARACTERS BEFORE SPACE.
    MOVE STR-OFFSET TO COMM-RPC-LIBRARY-OFFSET.
    MOVE STR-LENGTH TO COMM-RPC-LIBRARY-LENGTH.
    STRING RPCLIB DELIMITED BY SPACE INTO 
           COMM-STRING-AREA WITH POINTER STR-OFFSET.
   * Set CCSID for encoding of RPC userid/password and application data (Note 3)
    MOVE "37" TO COMM-CCSID.
   * Call generic RPC service module to create security token (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.
    . . .

After successful return from creating the security token with a long RPC user ID/RPC password:

• The authentication fields in the RPC communication area are properly set, so they can be used in subsequent RPC requests.

• The RPC protocol is forced to 2050 as a minium. You need an RPC server supporting this protocol level, see Supported RPC Protocols.

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.
3. If a CCSID is provided:

   • It is used for conversion of the long RPC password and RPC user ID. If no CCSID is provided, the codepage active during compilation applies. Refer to your compiler documentation.

   • It is used as the codepage name to tell the broker the encoding of your application data. See Using Internationalization with the COBOL Wrapper.