Using the COBOL Wrapper for the Server Side

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)

This section covers the following topics:

See also COBOL Scenarios in the RPC Server for CICS documentation.

Introduction

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

graphics/using-server_dfh-channel.png

(*) 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

Steps

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

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

  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 and Returning Application Errors.

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

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

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

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

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

This section covers the following topics:

See also COBOL Scenarios in the RPC Server for CICS documentation.

Introduction

This mode applies to z/OS.

graphics/using-server_dfh-channel.png

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

CICS Channel Container IDL Rules

The following rules apply to CICS channel container IDL:

Restrictions

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

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.

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:

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

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

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

  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 and Returning Application Errors under Scenarios and Programmer Information in the RPC Server for CICS documentation.

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

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

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

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

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.

Introduction

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

graphics/using-server_large.png

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

Steps

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

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

  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 and Returning Application Errors under Scenarios and Programmer Information in the RPC Server for CICS documentation.

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

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

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

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

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

This section covers the following topics:

See also COBOL Scenarios (z/OS | BS2000) in the RPC Server for Batch documentation.

Introduction

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

graphics/using-server_batch.png

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

Steps

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

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

  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.

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

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

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

      • Compile them as OM or LLM modules.

    • IBM i
      • 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.

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

    • IBM i
      • 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.

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

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

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

This section covers the following topics:

See also COBOL Scenarios in the RPC Server for IMS documentation.

Introduction

This mode applies to z/OS IMS mode BMP.

graphics/using-server_ims.png

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

IMS PCB Pointer IDL Rules

  • 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-Define

Steps

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

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

  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 and Returning Application Errors in the RPC Server for IMS documentation.

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

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

  7. Provide the server to the RPC Server for IMS.

    • Add the server to the RPC Server for IMS STEPLIB chain.

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