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 client applications written in COBOL.

• Using the COBOL Wrapper for CICS with DFHCOMMAREA Calling Convention (z/OS and z/VSE)

• Using the COBOL Wrapper for CICS with Call Interfaces (z/OS and z/VSE)

• Using the COBOL Wrapper for Batch (z/OS, BS2000, z/VSE and IBM i)

• Using the COBOL Wrapper for IMS (z/OS)

• Using the COBOL Wrapper for IDMS/DC with Call Interfaces (z/OS)

• Using the COBOL Wrapper for Micro Focus (UNIX and Windows)

A step-by-step guide is provided in the section Writing Applications with the COBOL Wrapper. Read this section first before writing your first RPC client program.

---

Using the COBOL Wrapper for CICS with DFHCOMMAREA Calling Convention (z/OS and z/VSE)

This mode applies to z/OS and z/VSE.

In this scenario, the generic RPC services module is installed only once within CICS as a CICS program and shared by all COBOL RPC client programs. Also, the COBOL client program and every generated client interface object are installed each as separate individual CICS programs.

Use the COBOL Wrapper for CICS with DFHCOMMAREA calling convention in the following situations:

• You want to have an EXEC CICS LINK DFHCOMMAREA interface to your client interface object(s).

• You wish to separate the generic RPC service module and the broker stub from the client interface object(s).

• You require a program link to the client interface object(s).

• You can accept the following restrictions:

  • The maximum COMMAREA length suits your purposes. Because the RPC communication area is also transferred in the COMMAREA, the effective length that can be used for IDL data is shorter than the CICS COMMAREA length. Nearly 31 KB can be used for IDL data.

  • No support for long broker passwords and long RPC user IDs/passwords.

  • No support for IDL unbounded arrays without maximum. See Mapping Fixed and Unbounded Arrays.

    Check if Using the COBOL Wrapper for CICS with Call Interfaces (z/OS and z/VSE) is an alternative for you.

To use the COBOL Wrapper for CICS with DFHCOMMAREA calling convention

1. Generate the client interface object 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. Check the option Generate the generic RPC service module COBSRVI.  More info

2. If necessary, use FTP to transfer the client interface object(s), and also the generic RPC service module COBSRVI, to the target platform where you write your client application.

3. Write your COBOL client program. If this is your first COBOL client program, refer to Writing EXEC CICS LINK Clients.

4. Using the CICS translator for COBOL provided with your CICS installation and a COBOL compiler supported by the COBOL Wrapper, translate and compile:

   • the generated client interface object(s)

   • if required, the generic RPC service module COBSRVI

   • your COBOL client program.

   Take care the generated copybooks (see Using the Generated Copybooks) are accessed correctly by the compiler and not confused with the client interface objects, because the copybooks and client interface objects have identical file names. See your compiler documentation.

5. Using the standard linker (binder) of the target platform, link (bind) the following programs to separate CICS programs:

   • every generated client interface object

   • if required, the generic RPC service module COBSRVI together with a broker stub

   • your COBOL client program.

6. Install every client interface object, if required the CICS RPC service module COBSRVI and your COBOL client program as separate CICS programs.

7. Make sure the correct broker stub is used and can be called dynamically by the CICS generic RPC service module COBSRVI.

   • z/OS
     See the broker installation documentation and use a broker stub for CICS (for example CICSETB) from the common load library EXX105.LOAD. See also Administering Broker Stubs.

   • z/VSE
     See the broker installation documentation and use a broker stub for CICS (for example BKIMC), see sublibrary EXX960.

Using the COBOL Wrapper for CICS with Call Interfaces (z/OS and z/VSE)

This mode applies to z/OS and z/VSE.

The COBOL Wrapper can be used with a call interface, even in CICS. This means you can build a client application where every generated client interface object, the generic RPC services module and the broker stub are linked together or called dynamically by the COBOL client program, similar to the batch scenario. See Using the COBOL Wrapper for Batch (z/OS, BS2000, z/VSE and IBM i).

Using a call interface within CICS may be useful if

• the maximum COMMAREA length for IDL data (about 31 KB) and other restrictions prevent you from using the Using the COBOL Wrapper for CICS with DFHCOMMAREA Calling Convention (z/OS and z/VSE) scenario

• you do not require a distributed program link (CICS DPL) to your client interface object(s)

• you prefer a call interface instead of EXEC CICS LINK to your client interface objects.

For platform z/OS this scenario supports the following:

• Long broker passwords. See Using Broker Logon and Logoff.

• Long RPC user IDs/passwords. See Using RPC Authentication (Natural Security, Impersonation, Integration Server).

• IDL unbounded groups or arrays without maximum mapped to COBOL's OCCURS 1 TO UNBOUNDED DEPENDING ON.

To use the COBOL Wrapper with a call interface within CICS

1. Generate the client interface object(s) for the target operating system, for example "z/OS", and use the interface type "CICS with standard calling convention". See Generating COBOL Source Files from Software AG IDL Files. Check the option Generate the generic RPC service module COBSRVI.  More info

2. If necessary, use FTP to transfer the client interface object(s), and also the generic RPC service module COBSRVI, to the target platform where you write your client application.

3. Write your COBOL client program. If this is your first COBOL client program, refer to Writing Standard Call Interface Clients.

4. Using the CICS translator for COBOL provided with your CICS installation and a COBOL compiler supported by the COBOL Wrapper, translate and compile:

   • the generated client interface object(s)

   • if required, the generic RPC service module COBSRVI

   • your COBOL client program

   Take care the generated copybooks (see Using the Generated Copybooks) are accessed correctly by the compiler and not confused with the client interface objects, because the copybooks and client interface objects have identical file names. See your compiler documentation.

5. Using the standard linker (binder) of the target platform, link (bind) all translated and compiled modules, and, if required, the broker stub, together to the client application (that is, a CICS program), using the standard linker (binder) of the target platform.

6. Install the client application within CICS.

7. Make sure the correct broker stub is used and can be called dynamically by the generic RPC service module COBSRVI.

   • z/OS
     See the broker installation documentation and use a broker stub for CICS (for example CICSETB) from the common load library EXX105.LOAD. See also Administering Broker Stubs.

   • z/VSE
     See the broker installation documentation and use a broker stub for CICS (for example BKIMC), see sublibrary EXX960.

Using the COBOL Wrapper for Batch (z/OS, BS2000, z/VSE and IBM i)

This mode applies to z/OS, BS2000, z/VSE and IBM i.

In this scenario, every generated client interface object, the generic RPC services module and the broker stub are linked together or called dynamically by the COBOL client program.

For platform z/OS this scenario supports the following:

• Long broker passwords. See Using Broker Logon and Logoff.

• Long RPC user IDs/passwords. See Using RPC Authentication (Natural Security, Impersonation, Integration Server).

• IDL unbounded groups or arrays without maximum mapped to COBOL's OCCURS 1 TO UNBOUNDED DEPENDING ON.

To use the COBOL Wrapper for batch

1. Generate the client interface object(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. Check the option Generate the generic RPC service module COBSRVI.  More info

2. If necessary, use FTP to transfer the client interface object(s), and also the generic RPC service module COBSRVI, to the target platform where you write your client application.

3. Write your COBOL client program. If this is your first COBOL client program, refer to Writing Standard Call Interface Clients.

4. Using a COBOL compiler supported by COBOL Wrapper, compile:

   • the generated client interface object(s)

   • if required, the generic RPC service module COBSRVI

   • your COBOL client program

   Take care the generated copybooks (see Using the Generated Copybooks) are accessed correctly by the compiler and not confused with the client interface objects, because the copybooks and client interface objects have identical file names. See your compiler documentation.

   • BS2000
     The IDL types U or UV require a compiler that supports COBOL data type NATIONAL. See BS2000 Prerequisites for more information on supported compilers.  More info

   • IBM i

     • Use the command CRTCBLMOD (create COBOL module) and compile all modules above to ILE modules.

     • Use the IBM i compiler command with the options shown below:

       CRTCBLMOD
       OPTION(*NOMONOPRC) EXTDSOPT(*NODFRWRT) LINKLIT(*PRC)

   • Other Platforms
     Use the standard COBOL compiler of the target platform.

5. Using the standard linker (binder) of the target platform, link (bind) the following programs:

   • the generated client interface object(s)

   • if required, the generic RPC service module COBSRVI

   • if required, the broker stub

   • your COBOL client program

   Depending on the platform:

   • IBM i
     Use the IBM i command CRTPGM to bind all compiled modules to an executable ILE program of type *PGM.
     To link the main program, use the following create program command with the options shown:

     CRTPGM
        MODULE(*LIB/myapplication mystub1 mystub2 ..)
        BNDSRVPGM(EXX/EXA) ...

     where EXX is the EntireX product library and EXA the broker stub.

   • Other Platforms
     Refer to your standard linker (binder) documentation.

6. Make sure that the correct broker stub module is used and, if linked (bound) dynamically, that it can be called dynamically.

   • z/OS
     See the broker installation documentation and use a broker stub for batch (for example BROKER) from the common load library EXX105.LOAD. See also Administering Broker Stubs.

   • z/VSE
     See the broker installation documentation and use a broker stub for batch (for example BKIMB), see sublibrary EXX960.

   • BS2000
     The broker stub module BROKER is located in the broker LMS load library.

   • IBM i
     The broker stub EXA is located by default in the EntireX product library EXX.

Using the COBOL Wrapper for IMS (z/OS)

This mode applies to z/OS IMS modes BMP and MPP.

In this scenario, every generated client interface object, the generic RPC services module and the broker stub are linked together or called dynamically by the COBOL client program.

For platform z/OS this scenario supports the following:

• Long broker passwords. See Using Broker Logon and Logoff.

• Long RPC user IDs/passwords. See Using RPC Authentication (Natural Security, Impersonation, Integration Server).

• IDL unbounded groups or arrays without maximum mapped to COBOL's OCCURS 1 TO UNBOUNDED DEPENDING ON.

To use the COBOL Wrapper for IMS

1. Generate the client interface object(s) for the target operating system "z/OS" and use the interface type "IMS BMP with standard linkage calling convention" or "IMS MMP with standard linkage calling convention". See Generating COBOL Source Files from Software AG IDL Files. Check the option Generate the generic RPC service module COBSRVI.  More info.

2. If necessary, use FTP to transfer the client interface object(s), and also the generic RPC service module COBSRVI, to the target platform where you write your client application.

3. Write your COBOL client program. If this is your first COBOL client program, refer to Writing Standard Call Interface Clients.

4. Using a COBOL compiler supported by the COBOL Wrapper, compile:

   • the generated client interface object(s)

   • if required, the generic RPC service module COBSRVI

   • your COBOL client program.

   Take care the generated copybooks (see Using the Generated Copybooks) are accessed correctly by the compiler and not confused with the client interface objects, because the copybooks and client interface objects have identical file names. Do not assign the data set with the client interface objects prior in sequence to the copybooks to SYSLIB. See your compiler documentation.

5. Link (bind) all compiled modules and, if required, the broker stub, together to an executable program, using the standard linker (binder) of the target platform.

6. Make sure the correct broker stub is used and can be called dynamically. In the common load library EXX105.LOAD you can find broker stubs that can be used for

   • IMS BMP (for example BROKER)

   • IMS MPP (for example MPPETB)

   See Administering Broker Stubs.

Using the COBOL Wrapper for IDMS/DC with Call Interfaces (z/OS)

This mode applies to z/OS.

The COBOL Wrapper can be used with a call interface in IDMS/DC. This means you can build an application where the COBOL client program, every generated client interface object, the generic RPC services module and the broker stub are linked together, similar to the batch scenario. See Using the COBOL Wrapper for Batch (z/OS, BS2000, z/VSE and IBM i).

To use the COBOL Wrapper with a call interface within IDMS/DC

1. Generate the client interface object(s) for the target operating system "z/OS", and use the interface type "IDMS/DC with standard calling convention". See Generating COBOL Source Files from Software AG IDL Files. Check the option Generate the generic RPC service module COBSRVI.  More info

2. If necessary, use FTP to transfer the client interface object(s), and also the generic RPC service module COBSRVI, to the target platform where you write your client application.

3. Write your COBOL client program. See Writing Applications with the COBOL Wrapper, in particular the section The RPC Communication Area (Reference), and take into consideration the information given in Software AG IDL to COBOL Mapping.

4. Write your COBOL client program. If this is your first COBOL client program, refer to Writing Standard Call Interface Clients.

5. Using the standard linker (binder) of the target platform, link (bind) all translated and compiled modules, and, if required, the broker stub, together to an IDMS/DC program, using the standard linker (binder) of the target platform.

6. Install the IDMS/DC program within IDMS/DC.

7. Make sure the correct broker stub is used and can be called dynamically by the generic RPC service module COBSRVI.

   See the broker installation documentation and use a broker stub for IDMS/DC (for example IDMSETB) from the common load library EXX105.LOAD. See also Administering Broker Stubs.

Using the COBOL Wrapper for Micro Focus (UNIX and Windows)

This mode applies to UNIX and Windows.

In this scenario, the COBOL client program, every generated client interface object, generic RPC services module and the broker stub are linked together to the client application.

To use the COBOL Wrapper for Micro Focus

1. Generate the client interface object(s) for the target operating system, for example "Windows", and use interface type "Micro Focus with standard linkage calling convention". See Generating COBOL Source Files from Software AG IDL Files. Check the option Generic the RPC service module COBSRVI.  More info

2. If necessary, use FTP to transfer the client interface object(s), and also the generic RPC service module COBSRVI, to the target platform where you write your client application.

3. Write your COBOL client program. If this is your first COBOL client program, refer to Writing Standard Call Interface Clients.

4. Compile and link (bind) all modules together to an executable program:

   • the generated client interface object(s)

   • if required, the generic RPC service module COBSRVI

   • your COBOL client program

   For target operating system Windows (i.e. the modules are generated for Windows):

   • No additional compiler directives and linker options are required.

5. Make sure the broker stub module can be called dynamically.

   • UNIX
     The broker stub shared library or object libbroker.so|sl is accessible according to the rules of the UNIX system used, e.g. the directory of the library is defined in the LD_LIBRARY_PATH environment variable.;

   • Windows
     The broker stub DLL broker.dll is accessible, for example with the PATH environment variable.