The COBOL Wrapper provides access to RPC-based components from COBOL applications and enables you to develop both clients and servers. This document introduces the various possibilities for RPC-based server applications written in COBOL and covers the following sections:
Using the COBOL Wrapper for CICS with DFHCOMMAREA Calling Convention (z/OS and z/VSE)
Using the COBOL Wrapper for CICS with Channel Container Calling Convention (z/OS)
Using the COBOL Wrapper for CICS with DFHCOMMAREA Large Buffer Interface (z/OS and z/VSE)
This section covers the following topics:
See also COBOL Scenarios in the RPC Server for CICS documentation.
This mode applies to z/OS and z/VSE.
| (*) | See Target Operating System and Server Interface Types under Generating COBOL Source Files from Software AG IDL Files. |
In CICS, the RPC server sets up all of your server's parameters
dynamically in the format required. Your server is called using EXEC CICS
LINK.
Use the COBOL Wrapper for CICS with DFHCOMMAREA calling convention if
you want to have a standard EXEC CICS LINK DFHCOMMAREA interface to
your server
you require a distributed program link (CICS DPL) to your server
the DFHCOMMAREA length restriction (31 KB) suits your needs, otherwise consider the following interface types:
To use the COBOL Wrapper for CICS with DFHCOMMAREA calling convention
Generate the server (skeleton) for the target operating system, for example "z/OS", and use interface type "CICS with DFHCOMMAREA calling convention". See Generating COBOL Source Files from Software AG IDL Files.
If a server mapping file is required, it has to be provided. A server mapping file is a Designer file with extension .cvm. See Server Mapping Files for COBOL. The server mapping files are wrapped into RPC clients and provided with the RPC request. You need to rebuild all RPC clients communicating with this RPC server program. Select the appropriate wrapper (see EntireX Wrappers in the Designer documentation) and re-generate the client interface objects. For the EntireX Adapter you need to update your generated IS adapter as described under To update an existing connection in Step 3: Create or Update an Adapter Connection in the Integration Server Wrapper documentation.
If necessary, use FTP to transfer the server (skeleton(s)) to the target platform where you write your server.
Use the generated server (skeleton(s)) and complete it by applying your application logic. Note the information given in Software AG IDL to COBOL Mapping and Returning Application Errors.
Using the CICS translator for COBOL provided with your CICS installation and a COBOL compiler supported by the COBOL Wrapper, translate and compile your server.
Link (bind) the server to an executable program, using the standard
linker (binder) of the target platform. Give your server a CICS program name
that is the same as the program-name in the IDL file. See program-definition under Software AG IDL Grammar in the IDL Editor documentation.
Provide your server(s) to the RPC Server for CICS, EntireX Adapter, or RPC Server for CICS ECI:
Install your server(s) as separate CICS program(s).
If you are using the RPC Server for CICS, before using your server(s), check if you need to alter
CICS settings - for example TWASIZE; see CICS Settings
for z/OS additionally IBM LE Runtime Options - for example AMODE24, how to trap ABENDS etc.
Test your server.
If you are using a server mapping file (.cvm), the server mapping is taken from the RPC request and the program with the COBOL name (see Note) defined in the server mapping is executed. See Customize Automatically Generated Server Names. If no corresponding program can be found, the access will fail.
If no server mapping file is required (see When is a Server Mapping File Required?)
or the server is generated with a previous version of EntireX without support for
server mapping - the library name (see library-definition)
given in the IDL is ignored (see Note).
Example: If a client performs an RPC request that is based on the IDL program name CALC, the RPC server will dynamically try to execute a program CALC. If no corresponding program can be found, the access will fail.
This section covers the following topics:
See also COBOL Scenarios in the RPC Server for CICS documentation.
This mode applies to z/OS.
| (*) | See Target Operating System and Server Interface Types under Generating COBOL Source Files from Software AG IDL Files. |
In CICS, the RPC server sets up all of your server's parameters
dynamically in the format required. Your server is called using EXEC CICS
LINK passing the container(s) in the defined channel to your server. See Channel Name.
Use the COBOL Wrapper for CICS with channel container calling convention if
you require more than 31 KB of data to transfer to your server
your IDL complies with CICS channel container IDL rules (see below).
If your IDL does not match these rules, consider the interface type
Using the COBOL Wrapper for CICS with DFHCOMMAREA Large Buffer Interface (z/OS and z/VSE) to implement your server.
you want to have a standard CICS channel container interface to your server
you require a distributed program link (CICS DPL) to your server.
The following rules apply to CICS channel container IDL:
A container is described with an IDL structure. See structure-definition.
The container name is the name of the IDL structure. A maximum of 16 characters are allowed by CICS for container names.
IDL programs reference IDL structures only. No other parameters may be referenced.
Multiple containers can be defined, see Example 3: Multiple Containers.
A variable number of containers can be defined using one-dimensional
IDL unbounded arrays with maximum (see array-definition under Software AG IDL Grammar in the IDL Editor documentation). See also
Example 4: Variable Number of Containers (Direction Out Only).
IDL unbounded arrays (i.e. variable containers) for direction In and
INOUT are not supported.
Two and three-dimensional IDL unbounded arrays are not supported.
This example uses the same container for input and output. The container name is "CALC".
Library 'EXAMPLE' Is
Program 'CONCALC' Is
Define Data Parameter
1 Container ('CALC') InOut
End-Define
Struct 'CALC' Is
Define Data Parameter
1 Operation (A1)
1 Operand_1 (I4)
1 Operand_2 (I4)
1 Function_Result (I4)
End-Define
This example uses separate containers for input and output.
Library 'DFHCON' Is
Program 'TWOC' Is /* Two Container - Separate for Input and Output
Define Data Parameter
1 ContainerIn ('CONTAINER1') In
1 ContainerOut ('CONTAINER2') Out
End-Define
Struct 'CONTAINER1' Is
Define Data Parameter
1 Just-Occupied-Space (A39000) /* 39K
1 Request (A1000/5) /* 5K
End-Define
Struct 'CONTAINER2' Is
Define Data Parameter
1 Just-Occupied-Space (A49000) /* 49K
1 Reply (A250)
End-Define
See IDL program TWOC under
Advanced CICS Channel Container RPC Server Example.
This example shows how more than one container is used per direction. Each container has its own structure layout.
Library 'DFHCON' Is
Program 'MULTIC' Is
Define Data Parameter
1 InContainer1 ('INCONTAINER1') In
1 InContainer2 ('INCONTAINER2') In
1 InContainer3 ('INCONTAINER3') In
...
1 OutContainer1 ('OUTCONTAINER1') Out
1 OutContainer2 ('OUTCONTAINER2') Out
1 OutContainer3 ('OUTCONTAINER3') Out
...
End-Define
Struct 'INCONTAINER1' Is ...
Struct 'INCONTAINER2' Is ...
Struct 'INCONTAINER3' Is ...
...
Struct 'OUTCONTAINER1' Is ...
Struct 'OUTCONTAINER1' Is ...
Struct 'OUTCONTAINER1' Is ...
...
This example shows how to specify a range of containers. At runtime, the called RPC server creates a variable number of containers from this range. Each container created has the same structure layout and a container name that is formed from the structure name as prefix and the structure index as suffix. In this example:
MULTIPLE container names are MULTIPLE0001
thru MULTIPLE9999.
OPTIONAL container name is OPTIONAL1.
Note:
Make sure IDL observes the 16-character length restriction for
container names given by CICS.
Library 'DFHCON' Is
Program 'VARC' Is
Define Data Parameter
1 Input ('INPUT') In
1 Multiple ('MULTIPLE'/V9999) Out /* 0 thru 9999 times
1 Optional ('OPTIONAL'/V1) Out /* 0 or 1 times
End-Define
Struct 'INPUT' Is ...
Struct 'MULTIPLE' Is ...
Struct 'OPTIONAL' Is ...
To use the COBOL Wrapper for CICS with channel container calling convention
Generate the server (skeleton(s)) for the target operating system, for example "z/OS", and use interface type "CICS with channel container calling convention". See Generating COBOL Source Files from Software AG IDL Files.
The generated server mapping file has to be provided. A server mapping file is a Designer file with extension .cvm. See Server Mapping Files for COBOL. The server mapping files are wrapped into RPC clients and provided with the RPC request. You need to rebuild all RPC clients communicating with this RPC server program. Select the appropriate wrapper (see EntireX Wrappers in the Designer documentation) and re-generate the client interface objects. For the EntireX Adapter you need to update your generated IS adapter as described under To update an existing connection in Step 3: Create or Update an Adapter Connection in the Integration Server Wrapper documentation.
If necessary, use FTP to transfer the server (skeleton(s)) to the target platform where you write your server.
Use the generated server (skeleton(s)) and complete it by applying your application logic. Note the information given in Software AG IDL to COBOL Mapping and Returning Application Errors under Scenarios and Programmer Information in the RPC Server for CICS documentation.
Using the CICS translator for COBOL provided with your CICS installation and a COBOL compiler supported by the COBOL Wrapper, translate and compile your server.
Link (bind) the server to an executable program, using the standard
linker (binder) of the target platform. Give your server a CICS program name
that is the same as the program-name in the IDL file (see program-definition).
Provide your server(s) to the RPC Server for CICS.
Install your server(s) as separate CICS program(s).
If you are using the RPC Server for CICS, before using your server(s), check if you need to alter
CICS settings - for example TWASIZE; see CICS Settings
for z/OS additionally IBM LE Runtime Options - for example AMODE24, how to trap ABENDS etc.
Test your server.
The generated server mapping is sent with the RPC request and the program with the COBOL name defined in the server mapping, is executed. See Customize Automatically Generated Server Names. If no corresponding program can be found, the access will fail.
This section covers the following topics:
See also COBOL Scenarios in the RPC Server for CICS documentation.
This mode applies to z/OS and z/VSE.
| (*) | See Target Operating System and Server Interface Types under Generating COBOL Source Files from Software AG IDL Files. |
In CICS, the RPC server sets up all your server's parameters
dynamically in the format required. Your server is called by EXEC CICS
LINK. Within the DFHCOMMAREA, pointers are passed to a large
input/output buffer.
Use the COBOL Wrapper for CICS with DFHCOMMAREA large buffer interface in the following situations:
You need to migrate COBOL programs implemented with webMethods WMTLSRVR interface to the RPC Server for CICS.
You require more than 31 KB of data to transfer to your server.
You cannot use the channel container calling convention because your IDL does not match the applicable rules; see CICS Channel Container IDL Rules under Using the COBOL Wrapper for CICS with Channel Container Calling Convention (z/OS). There are no IDL restrictions for this interface type - every IDL can be used.
You prefer this interface type rather than the channel container interface type.
You do not require a distributed program link (CICS DPL) to your server.
To use the COBOL Wrapper for CICS with large buffer interface
Generate the server (skeleton(s)) for the target operating system, for example "z/OS", and use interface type "CICS with DFHCOMMAREA large buffer interface". See Generating COBOL Source Files from Software AG IDL Files.
The generated server mapping file has to be provided. A server mapping file is a Designer file with extension .cvm. See Server Mapping Files for COBOL. The server mapping files are wrapped into RPC clients and provided with the RPC request. You need to rebuild all RPC clients communicating with this RPC server program. Select the appropriate wrapper (see EntireX Wrappers in the Designer documentation) and re-generate the client interface objects. For the EntireX Adapter you need to update your generated IS adapter as described under To update an existing connection in Step 3: Create or Update an Adapter Connection in the Integration Server Wrapper documentation.
If necessary, use FTP to transfer the server (skeleton(s)) to the target platform where you write your server.
Use the generated server (skeleton(s)) and complete it by applying your application logic. Note the information given in Software AG IDL to COBOL Mapping and Returning Application Errors under Scenarios and Programmer Information in the RPC Server for CICS documentation.
Using the CICS translator for COBOL provided with your CICS installation and a COBOL compiler supported by the COBOL Wrapper, translate and compile your server.
Link (bind) the server to an executable program, using the standard
linker (binder) of the target platform. Give your server a CICS program name
that is the same as the program-name in the IDL file (see program-definition).
Provide your server(s) to the RPC Server for CICS.
Install your server(s) as separate CICS program(s).
If you are using the RPC Server for CICS, before using your server(s), check if you need to alter
CICS settings - for example TWASIZE; see CICS Settings
for z/OS additionally IBM LE Runtime Options - for example AMODE24, how to trap ABENDS etc.
Test your server.
The generated server mapping is sent with the RPC request and the program with the COBOL name defined in the server mapping, is executed. See Customize Automatically Generated Server Names. If no corresponding program can be found, the access will fail.
This section covers the following topics:
See also COBOL Scenarios (z/OS | BS2000) in the RPC Server for Batch documentation.
This mode applies to z/OS, BS2000 and IBM i.
| (*) | See Target Operating System and Server Interface Types under Generating COBOL Source Files from Software AG IDL Files. |
In batch mode, the RPC server sets up all of your server's parameters dynamically in the format required. Your server is called dynamically using standard call interfaces.
Use the COBOL Wrapper for batch to build servers for the RPC Server for Batch.
To use the COBOL Wrapper for batch
Generate a server (skeleton(s)) for the target operating system, for example "z/OS", and use interface type "Batch with standard linkage calling convention". See Generating COBOL Source Files from Software AG IDL Files for details.
The generated server mapping file has to be provided. A server mapping file is a Designer file with extension .cvm. See Server Mapping Files for COBOL. The server mapping files are wrapped into RPC clients and provided with the RPC request. You need to rebuild all RPC clients communicating with this RPC server program. Select the appropriate wrapper (see EntireX Wrappers in the Designer documentation) and re-generate the client interface objects. For the EntireX Adapter you need to update your generated IS adapter as described under To update an existing connection in Step 3: Create or Update an Adapter Connection in the Integration Server Wrapper documentation.
If necessary, use FTP to transfer the server (skeleton(s)) to the target platform where you write your server.
Use the generated server (skeleton(s)) and complete it by applying your application logic. Note the information given in Software AG IDL to COBOL Mapping.
z/OS
See Returning Application Errors in the RPC Server for Batch documentation.
IBM i
Your server has to be implemented as an ILE COBOL program of type *PGM.
Use a COBOL compiler supported by the COBOL Wrapper to compile your server.
The IDL types U or UV require a compiler that supports COBOL data type NATIONAL. See BS2000 Prerequisites for more information on supported compilers.
Compile them as OM or LLM modules.
Use the IBM i command CRTCBLMOD (create
bound COBOL module).
As an alternative, you can compile and bind in one step, see the next step below.
Other Platforms
Use the standard COBOL compiler of the target platform.
Link (bind) your server to an executable program. Give the resulting
server program the same name as the program-name in the IDL file.
See program-definition under Software AG IDL Grammar in the IDL Editor documentation.
BS2000
There is no need to link the server modules with the BS2000
Common Runtime Environment (CRTE). The CRTE is included in the server's BLSLIB
chain and loaded dynamically. If this is needed for any reason, the CRTE must
be linked as a subsystem. All entries must be hidden to prevent duplicates.
Linking the CRTE statically will consume resources and slow down the load time
of the server modules.
Bind it as a dynamically callable program of type *PGM using the command CRTPGM.
Make sure your server fulfills all requirements to be callable by the IBM i host server.
As an alternative to compiling with
CRTCBLMOD (see step above) and binding with
CRTPGM separately, you can compile and bind in one
step with the command CRTBNDCBL.
Other Platforms
Use the standard linker (binder) of the target platform.
Provide your server to the endpoint, depending on the platform:
z/OS and BS2000
Add the server to the RPC Server for Batch STEPLIB chain.
IBM i
On your IBM i host server, put the server into a library corresponding to as400.programpath.
See Configuring the IBM AS/400 Side.
Test your server.
If you are using a server mapping file (.cvm), the server mapping is taken from the RPC request and the program with the COBOL name (see Note) defined in the server mapping is executed. See Customize Automatically Generated Server Names. If no corresponding program can be found, the access will fail.
If no server mapping file is required (see When is a Server Mapping File Required?)
or the server is generated with a previous version of EntireX without support for
server mapping - the library name (see library-definition)
given in the IDL is ignored (see Note).
Example: If a client performs an RPC request that is based on the IDL program name CALC, the RPC server will dynamically try to execute a program CALC. If no corresponding program can be found, the access will fail.
Note:
For IBM i this also depends on the setting as400.programpath.
See Configuring the IBM AS/400 Side in the RPC Server for AS/400 documentation.
This section covers the following topics:
See also COBOL Scenarios in the RPC Server for IMS documentation.
This mode applies to z/OS IMS mode BMP.
(*)See Target Operating System and Server Interface Types under Generating COBOL Source Files from Software AG IDL Files.
In IMS BMP, the RPC Server for IMS sets up all of your server's parameters dynamically in the format required. Your server is called dynamically using standard call interfaces. IMS-specific PCB pointers can be provided as parameters in the linkage section.
Use the COBOL Wrapper for IMS BMP if you need to
access IMS BMP programs with standard linkage calling convention
access IMS databases through IMS PCB pointers and to pass them via parameters in the linkage section
access the IMS PCB pointer IOPCB, for example to print data or to start an asynchronous transaction
use the COBOL/ DLI interface module "CBLTDLI" which requires PCB pointers in its interface.
If PCB pointers have to be provided as parameters in the COBOL linkage section of your server, your IDL must comply with the IMS PCB Pointer IDL rules listed below. If no PCB pointers are required, the rules can be skipped.
An IMS PSB list contains the PCB pointers of your environment:
The IMS PSB list is a text file and can be created with any text editor.
Only one PCB pointer is listed per line.
The PCB pointer IOPCB is always the first pointer in
the IMS PSB list.
The PCB pointers (except IOPCB) match the related PSB
generation for your server.
The PCB pointers listed match the PCB pointers provided at runtime
to the RPC Server for IMS (including IOPCB) in number and
sequence.
The IMS PSB list is assigned in the IDL properties, see Generating COBOL Source Files from Software AG IDL Files or IDL Generation Settings - Preferences. Example:
IOPCB DBPCB
PCB pointers are described in the IDL as parameters. Thus they can be accessed in your server as any other parameter. Additionally, the following is required:
IDL parameters that are PCB pointers are marked with the attribute
IMS (see attribute-list under Software AG IDL Grammar in the IDL Editor documentation).
IDL parameters that are PCB pointers must match a PCB pointer listed in the IMS PSB list, otherwise the RPC Server for IMS does not pass them as PCB pointers at runtime. This results in unexpected behavior. Example:
Library 'IMSDB' Is
Program ' IMSDB' Is
Define Data Parameter
1 IN-COMMAND (A3) IN /* ADD, DEL, DIS
1 IO-DATA IN OUT
2 IO-LAST-NAME (A10)
2 IO-FIRST-NAME (A10)
2 IO-EXTENSION (A10)
2 IO-ZIP-CODE (A07)
1 DBPCB IN IMS /* this is a PCB pointer
2 DBNAME (A8)
2 SEG-LEVEL-NO (A2)
2 DBSTATUS (A2)
2 FILLER1 (A20)
1 OUT-MESSAGE (A40) OUT
End-DefineTo use the COBOL Wrapper for IMS BMP
Generate the server (skeleton(s)) for the target operating system "z/OS", use interface type "IMS BMP with standard linkage calling convention". If PCB pointers should be provided as COBOL linkage section parameters for your server, set the IMS PSB list; otherwise omit the IMS PSB list. See Generating COBOL Source Files from Software AG IDL Files.
The generated server mapping file has to be provided. A server mapping file is a Designer file with extension .cvm. See Server Mapping Files for COBOL. The server mapping files are wrapped into RPC clients and provided with the RPC request. You need to rebuild all RPC clients communicating with this RPC server program. Select the appropriate wrapper (see EntireX Wrappers in the Designer documentation) and re-generate the client interface objects. For the EntireX Adapter you need to update your generated IS adapter as described under To update an existing connection in Step 3: Create or Update an Adapter Connection in the Integration Server Wrapper documentation.
If necessary, use FTP to transfer the server (skeleton(s)) to the target platform where you write your server.
Use the generated server (skeleton(s)) and complete it by applying your application logic. You can use the IMS-specific PCB pointers in your server as usual. Note the information given in Software AG IDL to COBOL Mapping and Returning Application Errors in the RPC Server for IMS documentation.
Using a COBOL compiler supported by the COBOL Wrapper, compile your server.
Link (bind) the server to an executable program, using the standard linker (binder) of the target program.
Give the resulting server program the same name as the program in
the IDL file (see program-definition under Software AG IDL Grammar in the IDL Editor documentation).
Provide the server to the RPC Server for IMS.
Add the server to the RPC Server for IMS STEPLIB chain.
Test your server.
If you are using a server mapping file (.cvm), the server mapping is taken from the RPC request and the program with the COBOL name (see Note) defined in the server mapping is executed. See Customize Automatically Generated Server Names. If no corresponding program can be found, the access will fail.
If no server mapping file is required (see When is a Server Mapping File Required?)
or the server is generated with a previous version of EntireX without support for
server mapping - the library name (see library-definition)
given in the IDL is ignored (see Note).
Example: If a client performs an RPC request that is based on the IDL program name CALC, the RPC server will dynamically try to execute a program CALC. If no corresponding program can be found, the access will fail.