Version 9.6
 —  EntireX COBOL Wrapper  —

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 Opt/
Req
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) used for Natural Security tokens. O I 4
COMM-USERID2 User ID extension. O I -
COMM-PASSWORD Password used for Natural Security tokens. O I 4
COMM-LIBRARY Library information used by Natural Security token. O I 4
COMM-SECURITY-TOKEN-LENGTH Length of Natural Security token. - O 4
COMM-SECURITY-TOKEN Natural Security token. - O -
COMM-IN-CONVERSATION Control variable internally used 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
COMM-IN-ACTIVE-UOW Control variable internally used 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 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 Corresponds to Broker ACI field SECURITY-TOKEN. A I/O -
COMM-ETB-CONV-ID Corresponds to Broker ACI field CONV-ID. A I/O 3
COMM-ETB-WAIT Corresponds to Broker ACI field WAIT. Default: 60 seconds. O I -
COMM-ETB-APIVERS Corresponds to Broker ACI field API-VERSION. Default=4. 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. A I/O 6
RPC Communication Area field

Name of the filed 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 Generic RPC Services 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. RPC conversations are supported when communicating with an RPC server. For more information, see Using Conversational RPC.
  4. Natural Security is only relevant if communicating with a Natural RPC server. See Using the COBOL Wrapper with Natural Security and Impersonation.
  5. See Reliable RPC for COBOL Wrapper.

Top of page

Generic RPC Services Modules

This section covers the following topics:

Introduction

The generic RPC services module COBSRVI is required for RPC clients.

Generic RPC Services Modules Usage

The delivered modules on mainframe platforms are mainly for a quick demonstration of the delivered examples. The best approach is to use the modules generated by the EntireX Workbench, for the following reasons:

Environment Scenarios Source to be Used Description Installation Linkage Usage
z/OS and z/VSE Batch. See Using the COBOL Wrapper for Batch (z/VSE, IBM i, BS2000/OSD and z/OS). COBSRVIB This module has a call interface to your COBOL RPC client application. Linked to your client application or can be called dynamically.
CICS with DFHCOMMAREA calling convention. See Using the COBOL Wrapper for CICS with DFHCOMMAREA Calling Convention (z/OS and z/VSE). COBSRVIC This module has an EXEC CICS LINK interface to your COBOL RPC client application. Installed only once within CICS as a CICS program and shared by all COBOL RPC client applications.
CICS with call interfaces. See Using the COBOL Wrapper for CICS with Call Interfaces (z/OS and z/VSE). COBSRVID This module has a call interface to your COBOL RPC client application. Linked to your client application or can be called dynamically.
z/OS IMS IMS. See Using the COBOL Wrapper for IMS (z/OS). COBSRVIB This module has a call interface to your COBOL RPC client application. Linked to your client application or can be called dynamically.
z/OS IDMS/DC IDMS/DC with call interfaces. See Using the COBOL Wrapper for IDMS/DC with Call Interfaces (z/OS). Not delivered. This module has a call interface to your COBOL RPC client application. Generate it with the EntireX Workbench. Linked to your client application or can be called dynamically.
BS2000/OSD Batch. See Using the COBOL Wrapper for Batch (z/VSE, IBM i, BS2000/OSD and z/OS). COBSRVI This module has a call interface to your COBOL RPC client application. Linked to your client application or can be called dynamically.
IBM i Batch. See Using the COBOL Wrapper for Batch (z/VSE, IBM i, BS2000/OSD and z/OS). RPCSRVI This module has a call interface to your COBOL RPC client application. Do not use this module; it is out of date. Generate it as COBSRVI with the EntireX Workbench. Linked to your client application or can be called dynamically.

Delivered Modules for z/OS

Module Data Set Description Notes
COBSRVIB EXP960.SRCE Batch generic RPC services with call interface. 2
COBSRVIC EXP960.SRCE CICS generic RPC services with EXEC CICS LINK interface. 2
COBSRVID EXP960.SRCE CICS generic RPC services with call interface. 2
COBIGYIC EXP960.SRCE JCL to compile the CICS generic RPC services module COBSRVIC with EXEC CICS LINK interface. 2
ERXCOMM EXP960.INCL RPC communication area. 1
ERXRCSRV EXP960.SRCE C main module for application errors. 3
ERXRCSRV EXP960.LD00 Ready-to-use ERXRCSRV module for application errors. 3
EXPCOBCL EXP960.JOBS JCL to compile the CICS generic RPC service module COBSRVIC with EXEC CICS LINK interface. 2
Module

Name of the delivered module.

vrs

Version, release and service pack.

EXP960.INCL

Generic RPC include data set. The generic RPC include data set may be delivered as a patch with a different name EXP960.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.

EXP960.SRCE

Generic RPC source data set. The generic RPC source data set may be delivered as a patch with a different name EXP960.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 Generic RPC Services Modules Usage.
  3. See Aborting RPC Server Customer Code and Returning Error to RPC Client (z/OS | z/VSE) in the CICS RPC Server 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 Generic RPC Services Modules Usage.
  3. We recommend you use module COBSRVI generated by the EntireX Workbench instead of the modules COBSRVIB, COBSRVIC and COBSRVID delivered with your z/VSE installation. The reason for this is that the EntireX Workbench is updated much more frequently. Section Generate Generic RPC Service for Module COBSRVI under Generating COBOL Source Files from Software AG IDL Files explains how to generate the RPC service module.

Delivered Modules for BS2000/OSD

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

Notes:

  1. See The RPC Communication Area (Reference).
  2. See Generic RPC Services Modules Usage
  3. We recommend you use module COBSRVI generated by the EntireX Workbench instead of the delivered module. The reason for this is that the EntireX Workbench is updated much more frequently. Section Generate Generic RPC Service for 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 Generic RPC Services Modules Usage
  3. Do not use module RPCSRVI delivered with your IBM i installation. It does not support all the features described here, for example reliable RPC. Use module COBSRVI generated by the EntireX Workbench instead. Section Generate Generic RPC Service for 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, SSL, 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 Administration of Broker Stubs under z/OS | UNIX | Windows | BS2000/OSD | 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.

Top of page