COBOL Wrapper Reference

This document covers the following topics:

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 table below for a complete listing.

Notes:

  1. See below the table for an explanation of column headings.
  2. The RPC communication area is provided with the generated copybook ERXCOMM in the folder include for RPC client generation. See Generating COBOL Source Files from Software AG IDL Files.
  3. See section Using the RPC Communication Area for the usage of the RPC communication area.
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. R I -
COMM-FUNCTION LO - log on to the Broker O I 1
LF - log off from the Broker 1
OC - open conversation 3
CE - close conversation with commit 3
CB - close conversation with backout 3
CT - create Natural Security token 4
RC - do reliable RPC commit 6
RR - do reliable RPC rollback 6
RS - get reliable status 6
EC - end of conversation 6
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 Message text provided by COBOL Wrapper (short versions). - O -
ERXCOMM-AREA1 Label. - - -
COMM-USERID Label. - - -
COMM-USERID1 User ID (8 characters) created into security token. O I 4
COMM-USERID2 User ID extension. O I -
COMM-PASSWORD Password (8 characters) created into security token. O I 4
COMM-LIBRARY Library name (8 characters) created into security token. O I 4,5
COMM-SECURITY-TOKEN-LENGTH Length of Natural Security token. - O 4
COMM-SECURITY-TOKEN Natural Security token. - O -
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 3,7
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,7
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 6
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.   O 6
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,2
COMM-ETB-PASSWORD Corresponds to Broker ACI field PASSWORD. O I 1,2
COMM-ETB-TOKEN Corresponds to Broker ACI field TOKEN. O I/O -
COMM-ETB-SECURITY-TOKEN Internal field. Corresponds to Broker ACI field SECURITY-TOKEN. A I/O 7
COMM-ETB-CONV-ID Internal field. Corresponds to Broker ACI field CONV-ID. A I/O 3,7
COMM-ETB-WAIT Corresponds to Broker ACI field WAIT. Default: 60 seconds. O I -
COMM-ETB-APIVERS Corresponds to Broker ACI field API-VERSION. O I -
COMM-ETB-UOW-ID Corresponds to Broker ACI field UOWID. O I/O 6
COMM-ETB-STORE Corresponds to Broker ACI field STORE. O I/O 6
COMM-ETB-PROGRAM-OFFSET Fields are used internally for accounting purposes. See Accounting in EntireX Broker under z/OS | UNIX | Windows | z/VSE. A I/O 7
COMM-ETB-LIBRARY-OFFSET A I/O 7
APPMON-SUPPORT Fields are used internally to support Application Monitoring A I/O 7
APPMON-VERIFY A I/O 7
APPMON-TIMEVALUE A I/O 7
APPMON-TRANSPORT-BUFFER A I/O 7
APPMON-LEN-TRANSPORT-BUFFER A I/O 7
APPMON-RECEIVE-BUFFER A I/O 7
APPMON-LEN-RECEIVE-BUFFER A I/O 7
APPMON-LEN-DATA A I/O 7
APPMON-RETURN-CODE A I/O 7
RPC Communication Area field

Name of the field in the RPC communication area.

Explanation

Explanation of the purpose of the field.

Req/Opt/Auto

Indicates for input fields whether they have to be given by the RPC application (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 application) or an output field (returned to your RPC application).

Notes:

  1. See Using Broker Logon and Logoff.
  2. Optional if broker does not require security; required if broker is secured.
  3. For RPC conversations. See Using Conversational RPC.
  4. Security credentials are relevant if communicating with a Natural RPC server running with Natural Security, or an RPC server running with impersonation; see Impersonation under z/OS (CICS, Batch, IMS) | z/VSE (CICS). See also Using the COBOL Wrapper with Natural Security and Impersonation.
  5. 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.
  6. See Reliable RPC for COBOL Wrapper.
  7. Field is managed internally by the Delivered Modules themselves. For these to work properly you need to initialize the RPC Communication Area before using it in your RPC client application. See Step 1: Declare and Initialize the RPC Communication Area. Do not change this field in your RPC client application.

Delivered Modules

This section covers the following topics:

Delivered Modules for z/OS

Module Data Set Description Notes
COBSRVI EXP103.SRCE CICS generic RPC services with EXEC CICS LINK interface. 2
ERXCOMM EXP103.INCL RPC communication area. 1
ERXRCSRV EXP103.SRCE C main module for application errors. 3
ERXRCSRV EXP103.LD00 Ready-to-use ERXRCSRV module for application errors. 3
EXPCSRVI EXP103.JOBS JCL to compile the CICS generic RPC service module COBSRVI with EXEC CICS LINK interface. 2
Module

Name of the delivered module.

EXP103.INCL

Generic RPC include data set. The generic RPC include data set may be delivered as a patch with a different name EXP103.INnn, where nn is the patch level number. Make sure you install the highest patch level available. The data set is required to SYSLIB input for the COBOL compiler.

EXP103.SRCE

Generic RPC source data set. The generic RPC source data set may be delivered as a patch with a different name EXP103.S0nn, where nn is the patch level number. Make sure you install the highest patch level available. The data set is required to SYSLIB input for the COBOL compiler.

Notes:

  1. See The RPC Communication Area (Reference).
  2. See Generate Generic RPC Service Module COBSRVI.
  3. See Aborting RPC Server Customer Code and Returning Error to RPC Client (z/OS | z/VSE) in the RPC Server for CICS documentation.

Delivered Modules for z/VSE

File Sublibrary Description Notes
ERXCOMM EXP960 RPC Communication area. 1
COBSRVIB.C EXP960 Batch generic RPC services with call interface (source). 2, 3
COBSRVIB.OBJ EXP960 Batch generic RPC services with call interface (object). 2, 3
COBSRVIC.C EXP960 CICS generic RPC services with EXEC CICS LINK interface (source). 2, 3
COBSRVIC.OBJ EXP960 CICS generic RPC services with EXEC CICS LINK interface (object). 2, 3
COBSRVID.C EXP960 CICS generic RPC services with call interface (source). 2, 3
COBSRVID.OBJ EXP960 CICS generic RPC services with call interface (object). 2, 3
File

Name of the delivered file.

Sublibrary

Name of the delivered sublibrary.

Description

Purpose of the file.

Notes:

  1. See The RPC Communication Area (Reference).
  2. See Generate Generic RPC Service Module COBSRVI.
  3. We recommend you use module COBSRVI generated by the Designer instead of the modules COBSRVIB, COBSRVIC and COBSRVID delivered with your z/VSE installation. The reason for this is that the Designer is updated much more frequently. Section Generate Generic RPC Service Module COBSRVI under Generating COBOL Source Files from Software AG IDL Files explains how to generate the RPC service module.

Delivered Modules for BS2000

Module Data Set Description Notes
ERXCOMM EXP103.COBC RPC communication area. 1
COBSRVI.COB EXP103.COBC Batch generic RPC services with call interface. 2, 3

Notes:

  1. See The RPC Communication Area (Reference).
  2. See Generate Generic RPC Service Module COBSRVI
  3. We recommend you use module COBSRVI generated by the Designer instead of the delivered module. The reason for this is that the Designer is updated much more frequently. Section Generate Generic RPC Service Module COBSRVI under Generating COBOL Source Files from Software AG IDL Files explains how to generate the RPC service module.

Delivered Modules for IBM i

Module Source file Description Notes
ERXCOMM QCBLLESRC RPC communication area. 1
RPCSRVI QCBLLESRC Batch generic RPC services with call interface. 2, 3

Notes:

  1. See The RPC Communication Area (Reference).
  2. See Generate Generic RPC Service Module COBSRVI.
  3. Do not use module RPCSRVI delivered with your IBM i installation. Use module COBSRVI generated by the Designer instead. Section Generate Generic RPC Service Module COBSRVI under Generating COBOL Source Files from Software AG IDL Files explains how to generate the RPC service module.

Adapting the Used Broker Stub

Because multiple broker stubs may be offered per operating system and environments, it may be necessary to adapt the COBSRVI module to the correct broker stub that supports the required transport (TCP, NET). To do this, modify the COBOL subprogram DOBROKER inside the COBSRVI source file with a broker stub that meets your requirements.

For availability and information on broker stubs, see Administering Broker Stubs under z/OS | UNIX | Windows | BS2000 | IBM i.

Caution:
Do not make any modifications other than changing the broker stub name, and do not modify the COBOL subprogram COBSRVI inside the same COBSRVI program source. Unexpected behavior will occur.