The RPC Communication Area (Reference)

The RPC communication area is used to specify parameters that are needed to communicate with the broker and are not specific to client interface objects. These are, for example, the Broker ID, client parameters such as user ID, password and the server address such as class/servername/service etc. See the tables below for a complete listing.

The RPC communication area is provided with the generated copybook ERXCOMM and optionally with its extension copybook ERXVSTR in the folder include for RPC client generation. See Generating COBOL Source Files from Software AG IDL Files.


Copybook ERXCOMM

The ERXCOMM copybook enables an RPC client to specify and retrieve data for RPC communication. For usage refer to ERXCOMM Copybook under Using the Generated Copybooks.

RPC Communication Area Field Explanation Req/
Opt/
Auto
In/
Out
Notes
ERXCOMM-HEADER Label. - - -
COMM-REQUEST Label. - - -
COMM-VERSION Version of RPC communication area. Possible values: 2000 or 4000. R I 7
COMM-FUNCTION LO - log on to the Broker O I 1
LF - log off from the Broker 1
OC - open conversation 2
CE - close conversation with commit 2
CB - close conversation with backout 2
CT - create Natural Security token 3
RC - do reliable RPC commit 5
RR - do reliable RPC rollback 5
RS - get reliable status 5
EC - end of conversation -
COMM-RETURN-CODE Message class and message code returned by COBOL Wrapper. - O -
COMM-MESSAGE-TEXT-EX Message text provided by COBOL Wrapper (long versions). - O -
COMM-MESSAGE-TEXT Deprecated. Use COMM-MESSAGE-TEXT-EX instead. - O -
ERXCOMM-AREA1 Label. - - -
COMM-USERID Label. - - -
COMM-USERID1 RPC user ID (8 characters) for RPC authentication. O I 3
COMM-USERID2 Deprecated - do not use. O I -
COMM-PASSWORD RPC password (8 characters) for RPC authentication. O I 3
COMM-LIBRARY RPC library name (8 characters) for RPC authentication or to log on to a specific library. O I 3,4
COMM-SECURITY-TOKEN-LENGTH Length of Natural Security token. A I/O 6
COMM-SECURITY-TOKEN Natural Security token. A I/O 6
COMM-IN-CONVERSATION Control variable used internally by generic RPC services and client interface objects. If set to Y, RPC requests will use COMM-ETB-CONV-ID for conversationality. A I/O 6
COMM-IN-ACTIVE-UOW Control variable used internally by generic RPC services and client interface objects for reliable RPC. If set to Y, RPC requests will use COMM-ETB-UOW-ID for reliability. A I/O 6
COMM-RELIABLE-STATE Control variable used by the application to determine whether standard RPC requests or reliable RPC messages are used. Valid values:
' ' (blank) normal RPC requests
A reliable RPC in AUTO-COMMIT mode
C reliable RPC in CLIENT-COMMIT mode
R I/O 5
COMM-RELIABLE-STATUS Result of a "get reliable status" call to generic RPC services, see field COMM-FUNCTION above. Values correspond to broker ACI field UOWSTATUS. A O 5
COMM-KERNEL-SECURITY Corresponds to Broker ACI field KERNELSECURITY. O I 1
COMM-CCSID This field is available for operating system z/OS only. Specify the CCSID for the following tasks: O I -
COMM-ETB-BROKER-ID Corresponds to Broker ACI field BROKER-ID. R I -
COMM-ETB-SERVER-CLASS Corresponds to Broker ACI field SERVER-CLASS. R I -
COMM-ETB-SERVER-NAME Corresponds to Broker ACI field SERVER-NAME. R I -
COMM-ETB-SERVICE-NAME Corresponds to Broker ACI field SERVICE. R I -
COMM-ETB-USER-ID Corresponds to Broker ACI field USER-ID. O I 1
COMM-ETB-PASSWORD Corresponds to Broker ACI field PASSWORD. O I 1
COMM-ETB-TOKEN Corresponds to Broker ACI field TOKEN. O I/O -
COMM-ETB-SECURITY-TOKEN Corresponds to Broker ACI field SECURITY-TOKEN. A I/O 6
COMM-ETB-CONV-ID Corresponds to Broker ACI field CONV-ID. A I/O 6
COMM-ETB-WAIT Corresponds to Broker ACI field WAIT. Default: 60 seconds. O I -
COMM-ETB-APIVERS Corresponds to Broker ACI field API-VERSION. A I/O 6
COMM-ETB-UOW-ID Corresponds to Broker ACI field UOWID. O I/O 5
COMM-ETB-STORE Corresponds to Broker ACI field STORE. O I/O 5
COMM-ETB-PROGRAM-OFFSET Fields are used internally to support Application Monitoring and for accounting purposes. See Accounting in EntireX Broker under z/OS | UNIX | Windows | z/VSE | BS2000. A I/O 6
COMM-ETB-LIBRARY-OFFSET A I/O 6
COMM-ETB-MESSAGE-ID Corresponds to Broker ACI field MESSAGE-ID. A O -
COMM-ETB-CORRELATION-ID Corresponds to Broker ACI field CORRELATION-ID. A O -
APPMON-SUPPORT Fields are used internally to support Application Monitoring A I/O 6
APPMON-VERIFY A I/O 6
APPMON-TIMEVALUE A I/O 6
APPMON-TRANSPORT-BUFFER A I/O 6
APPMON-LEN-TRANSPORT-BUFFER A I/O 6
APPMON-RECEIVE-BUFFER A I/O 6
APPMON-LEN-RECEIVE-BUFFER A I/O 6
APPMON-LEN-DATA A I/O 6
APPMON-RETURN-CODE A I/O 6

Key

Req/Opt/Auto

Indicates for input fields whether they have to be given by the RPC client (required) or may be given by the user (optional). Fields marked with "Auto" are managed internally by the Delivered Modules themselves.

In/Out

Indicates whether the field is an input field (to be given by the RPC client) or an output field (returned to your RPC client).

Notes:

  1. See Using Broker Logon and Logoff.
  2. For RPC conversations. See Using Conversational RPC.
  3. See Using RPC Authentication (Natural Security, Impersonation, Integration Server).
  4. If you are communicating with a non-secure Natural RPC Server you can set the Natural library. See Using the COBOL Wrapper with Non-secure Natural RPC Server.
  5. See Reliable RPC for COBOL Wrapper.
  6. Control variable used internally by generic RPC services and client interface objects. This means the field is managed internally by the Delivered Modules themselves.

Copybook ERXVSTR

The optional ERXVSTR copybook is an extension to the ERXCOMM copybook. It enables an RPC client to specify long data strings (e.g. passwords). For usage see ERXVSTR Copybook under Using the Generated Copybooks.

This table describes the fields in the RPC Variable String Area.

RPC Variable String Area Field Explanation Req/
Opt/
Auto
In/
Out
Notes
ERXCOMM-AREA2 Label. - - -
COMM-STRING-HEADER Label. - - -
COMM-ETB-PASSWORD-OFFSET   O I 1
COMM-ETB-PASSWORD-LENGTH   O I 1
COMM-RPC-USERID-OFFSET   O I 2
COMM-RPC-USERID-LENGTH   O I 2
COMM-RPC-PASSWORD-OFFSET   O I 2
COMM-RPC-PASSWORD-LENGTH   O I 2
COMM-RPC-LIBRARY-OFFSET   O I 2
COMM-RPC-LIBRARY-LENGTH   O I 2
COMM-STRING-AREA   O I 1,2

Notes:

  1. See Using Broker Logon and Logoff.
  2. See Using RPC Authentication (Natural Security, Impersonation, Integration Server).