Version 9.5 SP1
 —  EntireX COBOL Wrapper  —

Using the COBOL Wrapper for the Server Side

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


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

This mode applies to UNIX and Windows.

graphics/cobolServerside_microFocus.png

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

The Micro Focus 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 Wrapperfor Micro Focus to build servers for the Micro Focus RPC server.

Start of instruction setTo use the COBOL Wrapper for Micro Focus

  1. Generate a server (skeleton(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 for details.

  2. If a server mapping file (SVM file) is required, deploy it to the Micro Focus RPC Server, see Server Mapping Deployment.

  3. If necessary, use FTP to transfer the server (skeleton(s)) to the target platform where you write your server.

  4. Import the modules into your Micro Focus IDE.

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

  6. Compile and - if the format requires it - link (bind) and package your server(s) to one of the following formats:

  7. Provide your server to the Micro Focus RPC server.

Top of page

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

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

graphics/cobolServerside_batch.png

(*) For the target operating systems and interface types, see Generate COBOL Source Files from Software AG IDL Files.
(**) Currently an SVM file is generated for operating systems z/OS and z/VSE.

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 Batch RPC server.

Start of instruction setTo use the COBOL Wrapper for batch

  1. 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 Generate COBOL Source Files from Software AG IDL Files for details.

  2. If an SVM file is required, deploy it to the Batch RPC Server, see Server Mapping Deployment.

  3. If necessary, use FTP to transfer the server (skeleton(s)) to the target platform where you write your server.

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

    Under IBM i , consider multithreading issues:

  5. If necessary, use FTP to transfer your server to the target platform where you compile your server.

  6. Use a COBOL compiler supported by the COBOL Wrapper to compile your server.

    Under BS2000/OSD,

    Under IBM i,

    Under all other platforms,

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

    Under BS2000/OSD:

    Under IBM i:

    Under all other platforms

  8. Provide your server to the Batch RPC Server.

    Under IBM i

    Under all other platforms

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/cobolServerside_cics.png

(*) For the target operating systems and interface types, see Generate 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

Start of instruction setTo use the COBOL Wrapper for CICS with DFHCOMMAREA calling convention

  1. Generate the server (skeleton) for the target operating system, for example "z/OS", and use interface type "CICS with DFHCOMMAREA calling convention". See Generate COBOL Source Files from Software AG IDL Files.

  2. If an SVM file is required, it has to be provided. For the CICS RPC Server or CICS ECI RPC Server this is done by deployment, see Server Mapping Deployment. For the webMethods EntireX Adapter, it is picked up automatically when the adapter connection is generated.

  3. If necessary, use FTP to transfer the server (skeleton(s)) to the target platform where you write your server.

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

  5. If necessary, use FTP to transfer your server to the target platform where you compile your server.

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

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

  8. Provide your server(s) to the CICS RPC server, EntireX Adapter, or CICS ECI RPC server:

Top of page

Using the COBOL Wrapper for CICS with Channel Container Calling Convention (z/OS)

This section covers the following topics:

Introduction

This mode applies to z/OS.

graphics/cobolServerside_cics.png

(*) For the target operating systems and interface types, see Generate 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

CICS Channel Container IDL Rules

The following rules apply to CICS channel container IDL:

Restrictions

Example 1: Same Container for Direction In and Out

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

Example 2: Different Container for Direction In and Out

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

Example 3: Multiple Containers

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

Example 4: Variable Number of Containers (Direction Out Only)

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:

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

Steps

Start of instruction setTo use the COBOL Wrapper for CICS with channel container calling convention

  1. 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 Generate COBOL Source Files from Software AG IDL Files.

  2. Deploy the SVM file to the CICS RPC server. See Server Mapping Deployment.

  3. If necessary, use FTP to transfer the server (skeleton(s)) to the target platform where you write your server.

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

  5. If necessary, use FTP to transfer your server to the target platform where you compile your server.

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

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

  8. Provide your server(s) to the CICS RPC server.

Top of page

Using the COBOL Wrapper for CICS with DFHCOMMAREA Large Buffer Interface (z/OS and z/VSE)

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

graphics/cobolServerside_large.png

(*) For the target operating systems and interface types, see Generate 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:

Start of instruction setTo use the COBOL Wrapper for CICS with large buffer interface

  1. 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 Generate COBOL Source Files from Software AG IDL Files.

  2. Deploy the SVM file to the CICS RPC server. See Server Mapping Deployment.

  3. If necessary, use FTP to transfer the server (skeleton(s)) to the target platform where you write your server.

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

  5. If necessary, use FTP to transfer your server to the target platform where you compile your server.

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

  7. Link (bind) the server to an executable program, using the standard linker (binder) of the target platform. Give your server a CICS program name the same as the program-name in the IDL file. See program-definition under Software AG IDL Grammar.

  8. Provide your server(s) to the CICS RPC server.

Top of page

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

This mode applies to z/OS IMS mode BMP.

graphics/cobWrapper_ims.png

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

In IMS BMP, the IMS RPC server 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

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.

IMS PCB Pointer IDL Rules

Start of instruction setTo use the COBOL Wrapper for IMS BMP

  1. 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 Generate COBOL Source Files from Software AG IDL Files.

  2. If an SVM file is required, deploy it to the IMS RPC server, see Server Mapping Deployment.

  3. If necessary, use FTP to transfer the server (skeleton(s)) to the target platform where you write your server.

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

  5. If necessary, use FTP to transfer your server to the target platform where you compile your server.

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

  7. Link (bind) the server to an executable program, using the standard linker (binder) of the target program.

  8. Provide the server to the IMS RPC server.

Top of page