This document covers the following topics:
Logging on Using Short Broker Passwords (all Interface Types)
Logging on Using Long Broker Passwords (z/OS with Call Interface)
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
LOGON
and 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 and Certificates with EntireX in the Platform-independent Administration documentation.
This approach allows a maximum of 32 bytes for the broker password. The code you write depends on the interface type:
This interface type applies to the scenarios CICS | Batch | IMS | Micro Focus.
To log on to the Broker with a short password
ERXCOMM
is Used under Step 1: Declare and Initialize the RPC Communication Area in section Writing Standard Call Interface Clients.
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 ...
Issue your RPC requests as usual, without using explicit logon and logoff.
To 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.
This interface type applies to the scenario Using the COBOL Wrapper for CICS with DFHCOMMAREA
Calling Convention (z/OS and z/VSE).
To log on to the Broker with a short password
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.
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 ...
Issue your RPC requests as usual, without using explicit logon and logoff.
To 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:
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 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:
To log on to the Broker with a long password
ERXCOMM
and ERXVSTR
are Used under Step 1: Declare and Initialize the RPC Communication Area in section Writing Standard Call Interface Clients.
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. . . .
To 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:
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.