This document covers the following topics:
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)
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) | z/VSE (CICS).
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 and Certificates with EntireX in the Platform-independent Administration documentation.
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:
This interface type applies to the scenarios CICS | Batch | IMS | Micro Focus.
To use RPC authentication using short RPC user ID, RPC password and RPC library
ERXCOMM
is Used under Step 1: Declare and Initialize the RPC Communication Area in section Writing Standard Call Interface Clients.
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.
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
Declare the RPC communication area as described under Step 1: Declare IDL Structures and RPC Communication Area in section Writing EXEC CICS LINK
Clients.
Initialize the RPC communication area as described under Step 2: Initialize the RPC Communication Area under Writing EXEC CICS LINK
Clients.
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:
ERXCOMM
only, pass only the address of ERXCOMM
to the generic RPC service module.
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.
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:
To use RPC authentication with long RPC user ID, RPC password and RPC library
ERXCOMM
and ERXVSTR
are Used under Step 1: Declare and Initialize the RPC Communication Area in section Writing Standard Call Interface Clients.
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:
ERXCOMM
,
then the address of ERXVSTR
to the generic RPC service module.
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.
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.