Version 9.5 SP1
 —  EntireX COBOL Wrapper  —

Using the COBOL Wrapper for the Client Side

The COBOL Wrapper provides access to RPC-based components from COBOL applications and enables users to develop both clients and servers. This section introduces the various possibilities for RPC-based client applications written in COBOL.

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 Micro Focus (UNIX and Windows)

This mode applies to UNIX and Windows.

graphics/cobWrapper_microFocusBatch.png

(*) For the target operating systems and interface types, see Generate COBOL Source Files from Software AG IDL Files.

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

Use the COBOL Wrapper for Micro Focus if you need to embed the client interface object into your application with a standard linkage calling convention.

Start of instruction setTo 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 Generate COBOL Source Files from Software AG IDL Files. If required, generate the generic RPC service module COBSRVI too. See Generate Generic RPC Service for Module COBSRVI for information on when to generate this.

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

  3. Import the modules into your Micro Focus IDE. The file names of the generated copybooks (see Using the Generated Copybooks) are derived from the IDL program name or its alias if present. The file names are the same as the file names of the client interface objects. They are distinguished by their extension, ".cbl" for the client interface objects and ".cpy" for the copybooks. If you import the generated copybooks and client interface objects into your Micro Focus development environment, take care the copybooks are accessed correctly by the compiler and not confused with the client interface objects. This may happen if you copy the generated coybooks and the client interface objects into one directory. See your Micro Focus documentation for more information.

  4. Write your COBOL RPC client application. See Writing Applications with the COBOL Wrapper, in particular the section Using the RPC Communication Area with a Standard Call Interface, and take into consideration the information given in Software AG IDL to COBOL Mapping.

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

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

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

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

    Under UNIX:

    Under Windows:

Top of page

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

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

graphics/cobWrapper_microFocusBatch.png

(*) For the target operating systems and interface types, see Generate COBOL Source Files from Software AG IDL Files.

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

Use the COBOL Wrapper for batch if you need to embed the client interface object into your application with a standard linkage calling convention.

Start of instruction setTo 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 Generate COBOL Source Files from Software AG IDL Files. If required, generate the generic RPC service module COBSRVI too. See Generate Generic RPC Service for Module COBSRVI for information on when to generate this.

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

  3. If you have generated the generic RPC service module, you may need to adapt the broker stub that supports the required transport (TCP, SSL, NET). See Adapting the Used Broker Stub.

  4. Write your COBOL RPC client application. See Writing Applications with the COBOL Wrapper, in particular the section Using the RPC Communication Area with a Standard Call Interface, and take into consideration the information given in Software AG IDL to COBOL Mapping.

  5. If necessary, use FTP to transfer the client interface object(s), if required the generic RPC service module COBSRVI,and your application to the target platform where you compile your application.

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

    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.

    Under BS2000/OSD:

    Under IBM i:

    Under all other platforms:

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

    Under IBM i:

    Under all other platforms:

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

    Under BS2000/OSD:

    Under IBM i:

    Under z/OS:

    Under z/VSE:

Top of page

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

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

graphics/cobWrapper_cics.png

(*) For the target platforms, see Generate COBOL Source Files from Software AG IDL Files.

In this scenario, the generic RPC services module and the broker stub are linked together to a CICS program. The COBOL RPC client customer application, every generated client interface object and the generic RPC services module together with the broker stub are installed each as separate individual CICS programs.

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

Start of instruction setTo 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 DFCOMMAREA calling convention". See Generate COBOL Source Files from Software AG IDL Files. If required, generate the generic RPC service module COBSRVI too. See Generate Generic RPC Service for Module COBSRVI for information on when to generate this.

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

  3. If you have generated the generic RPC service module and you plan to (re)install it within CICS, you may need to adapt the broker stub that supports the required transport (TCP, SSL, NET). See Adapting the Used Broker Stub.

  4. Write your COBOL RPC client application. See Writing Applications with the COBOL Wrapper, in particular the section Using the RPC Communication Area with EXEC CICS LINK, and take into consideration the information given in Software AG IDL to COBOL Mapping.

  5. If necessary, use FTP to transfer the client interface object(s), if required the generic RPC service module COBSRVI,and your application to the target platform where you compile your application.

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

    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.

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

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

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

    Under z/OS:

    Under z/VSE:

Top of page

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

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

graphics/cobWrapper_cicsCallinterface.png

(*) For the target operating systems and interface types, see Generate COBOL Source Files from Software AG IDL Files.

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

Using a call interface within CICS may be useful if

Start of instruction setTo 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 Generate COBOL Source Files from Software AG IDL Files. If required, generate the generic RPC service module COBSRVI too. See Generate Generic RPC Service for Module COBSRVI for information on when to generate this.

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

  3. If you have generated the generic RPC service module, you may need to adapt the broker stub that supports the required transport (TCP, SSL, NET). See Adapting the Used Broker Stub.

  4. Write your COBOL RPC client application. See Writing Applications with the COBOL Wrapper, in particular the section Using the RPC Communication Area with a Standard Call Interface, and take into consideration the information given in Software AG IDL to COBOL Mapping.

  5. If necessary, use FTP to transfer the client interface object(s), if required the generic RPC service module COBSRVI, and your application to the target platform where you compile your application.

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

    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.

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

  8. Install the program within CICS.

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

    Under z/OS:

    Under z/VSE:

Top of page

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

This mode applies to z/OS.

graphics/cobWrapper_cicsCallinterface.png

(*) For the target operating systems and interface types, see Generate COBOL Source Files from Software AG IDL Files.

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

Start of instruction setTo 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 Generate COBOL Source Files from Software AG IDL Files. If required, generate the generic RPC service module COBSRVI too. See Generate Generic RPC Service for Module COBSRVI for information on when to generate this.

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

  3. If you have generated the generic RPC service module, you may need to adapt the broker stub that supports the required transport (TCP, SSL, NET). See Adapting the Used Broker Stub.

  4. Write your COBOL RPC client application. See Writing Applications with the COBOL Wrapper, in particular the section Using the RPC Communication Area with a Standard Call Interface, and take into consideration the information given in Software AG IDL to COBOL Mapping.

  5. If necessary, use FTP to transfer the client interface object(s), if required the generic RPC service module COBSRVI, and your application to the target platform where you compile your application.

  6. Using the IDMS/DC translator for COBOL provided with your IDMS/DC installation and a COBOL compiler supported by the COBOL Wrapper, translate and compile:

    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.

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

  8. Install the program within IDMS/DC.

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

    Under z/OS:

Top of page

Using the COBOL Wrapper for IMS (z/OS)

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

graphics/cobWrapper_client_ims.png

(*) For the target operating systems and interface types, see Generate COBOL Source Files from Software AG IDL Files.

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

Use the COBOL Wrapper for IMS if

Start of instruction setTo 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 Generate COBOL Source Files from Software AG IDL Files. See Generate Generic RPC Service for Module COBSRVI for information on when to generate this.

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

  3. If you have generated the generic RPC service module, you may need to adapt the broker stub that supports the required transport (TCP, SSL, NET). See Adapting the Used Broker Stub.

  4. Write your COBOL RPC client application. See Writing Applications with the COBOL Wrapper, in particular the section Using the RPC Communication Area with a Standard Call Interface, and take into consideration the information given in Software AG IDL to COBOL Mapping.

  5. If necessary, use FTP to transfer the client interface object(s), if required the generic RPC service module COBSRVI, and your application to the target platform where you translate and compile your application.

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

    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.

  7. 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.

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

    See Administration of Broker Stubs under z/OS.

Top of page