Generating COBOL Source Files from Software AG IDL Files

This document describes how to generate COBOL source files from Software AG IDL files. It covers the following topics:


Select an IDL File and Generate RPC Client or RPC Server

From the context menu, choose COBOL > Generate RPC Client and Generate RPC Server to generate the COBOL source files.

graphics/using-generate_selectIdl.png

Note:
In command-line mode, use command -cobol:client or -cobol:server. See Using the COBOL Wrapper in Command-line Mode. Note that existing files will always be overwritten.

Results for RPC client:

  • The folders client and include are created as subfolders to the IDL-specific Output Folder defined in the Generation Settings - Properties.

  • The client folder contains the client interface objects, and optionally the generic RPC service module. See Delivered Modules.

  • The folder include contains the associated copybooks, the RPC communication area copybook ERXCOMM and optionally the copybooks COBINIT and COBEXIT.

Notes:

  1. The generic RPC service module COBSRVI is only generated if the option Generate Generic RPC Service Module COBSRVI is set, see Generate Generic RPC Service Module COBSRVI.
  2. For further information on the purpose and usage of associated copybooks, see Using the Generated Copybooks.
  3. For further information on the purpose and usage of the RPC communication area copybook ERXCOMM , see Using the RPC Communication Area.
  4. The copybooks COBINIT and COBEXIT are only generated if Copybook has been selected as RPC Communication Area.

Results for RPC server:

  • The folder server is created as a subfolder to the IDL-specific Output Folder defined in the Generation Settings - Properties. It contains the RPC server skeletons.

    Warning:
    Take care not to overwrite an existing RPC server implementation with an RPC server skeleton. We recommend moving your RPC server implementation to a different folder.
  • If required, a server mapping file is generated, too. See When is a Server Mapping File Required? in the EntireX Workbench documentation. The server mapping file is of type client-side (extension .cvm) or server-side (.svm). See How to Set the Type of Server Mapping Files.

    • If you are using client-side mapping files, the following dialog is displayed.

      graphics/using-generate_selectIdl-client.png

      You need to rebuild all RPC clients communicating with this RPC server program. Select the appropriate wrapper (see EntireX Wrappers in the EntireX Workbench 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 you are using server-side mapping files, a dialog like below (with slight variations per interface type) is displayed:

      graphics/using-generate_selectIdl-server.png

      The generated server-side mapping file need to be synchronized with the server-side mapping container of the target RPC server. For EntireX Adapter they are wrapped into the generated Integration Server adapter - the same as client-side mapping files, see Integration Server Wrapper.

Start of instruction setTo quit the COBOL Wrapper and deploy the server-side mapping file

  1. Check the option Synchronize with server-side mapping container now and choose OK. This calls the Deployment Wizard. See Server Mapping Deployment Wizard in the EntireX Workbench documentation.

  2. Continue with Using the COBOL Wrapper for the Server Side.

Start of instruction setTo quit the COBOL Wrapper without deploying the server-side mapping file

  1. Clear the option Synchronize with server-side mapping container now and choose OK.

  2. Continue with Using the COBOL Wrapper for the Server Side.

Generation Settings - Properties

This section covers the following topics:

Introduction

Whenever a new IDL file is created, defaults for the properties are copied from the preferences. See Generation Settings - Preferences. To set individual properties per IDL file for COBOL Wrapper generation, use the Properties wizard of the IDL file. The Target Operating System) and the Interface Type are essential. They determine if other parameters such as RPC Communication Area provided by can be set or have to remain fixed. The parameter IDL-specific Output defines the location to store the source file subfolders. Target Operating System determines whether file extensions are generated or not.

graphics/using-generate_props_intro.png

In the following, we give a detailed description of the properties that need to be set for each type of generation:

Target Operating System

Select the target operating system for which COBOL code is to be generated. See Platform Coverage for a full list of supported operating system versions.

Value Description
z/OS IBM z/OS operating system.
z/VSE IBM z/VSE operating system.
BS2000 Fujitsu Siemens BS2000 operating system.
IBM i IBM i operating system.
Windows Microsoft Windows operating system.
UNIX UNIX operating system.

Characters Used for String Literals

With this option you can specify how string literals are specified in the generated COBOL code. See your COBOL compiler documentation for information on how string literals are enclosed.

Value Description
Quote String literals will be enclosed in double quotes in the generated COBOL code.
Apostrophe String literals will be enclosed in apostrophes (single quotes) in the generated COBOL code.

IDL-specific Output Folder

This field specifies the folder where the COBOL files will be stored, by default in the same folder as the IDL file. For a non-default location, enter another folder name or choose Browse....

Client Interface Types

Interface Type Target Operating System Scenario Generic RPC Services Module Usage (1) RPC Communication Area Usage
CICS with DFHCOMMAREA calling convention z/OS, z/VSE (2) Use this option if you want to build a CICS RPC client application that calls the client interface object(s) with the DFHCOMMAREA interface. Follow the steps under Using the COBOL Wrapper for CICS with DFHCOMMAREA Calling Convention (z/OS and z/VSE). The generic RPC service module COBSRVI for CICS with DFHCOMMAREA calling convention is installed only once within CICS as a CICS program and shared by all COBOL RPC client applications. The module has an EXEC CICS LINK interface to your COBOL RPC client application. The RPC communication area is passed as a separate parameter in the DFHCOMMAREA. See Using the RPC Communication Area with EXEC CICS LINK and RPC Communication Area.
CICS with standard linkage calling convention z/OS, z/VSE (2) Use this option if you want to build a CICS RPC client application that calls the client interface object(s) with a standard linkage interface. Follow the steps under Using the COBOL Wrapper for CICS with Call Interfaces (z/OS and z/VSE). The generic RPC service module COBSRVI for CICS with standard linkage calling convention is linked to your client application or can be called dynamically. The module has a call interface to your COBOL RPC client application. The RPC communication area is passed with one of the following options:
  • as a separate parameter in the call interface of the client interface object

  • With a COBOL EXTERNAL clause if a static link to the generic RPC service module is favored

  • embedded as a copybook in the client interface object and therefore invisible in the client application

See Using the RPC Communication Area with a Standard Call Interface and RPC Communication Area.

Batch with standard linkage calling convention z/OS, z/VSE (2), BS2000, IBM i (3) Use this option if you want to build a batch RPC client application that calls the client interface object(s) with a standard linkage interface. Follow the steps under Using the COBOL Wrapper for Batch (z/OS, BS2000, z/VSE and IBM i). The generic RPC service module COBSRVI with standard linkage calling convention is linked to your client application or can be called dynamically. The module has a call interface to your COBOL RPC client application.
IMS BMP with standard linkage calling convention z/OS (4) Use this option if you want to build an IMS RPC client application that calls the client interface object(s) with a standard linkage interface for IMS BMP mode. Follow the steps under Using the COBOL Wrapper for IMS (z/OS). The module has a call interface to your COBOL RPC client application.
IMS MPP with standard linkage calling convention z/OS (4) Use this option if you want to build an IMS RPC client application that calls the client interface object(s) with a standard linkage interface for IMS MPP mode. Follow the steps under Using the COBOL Wrapper for IMS (z/OS). The module has a call interface to your COBOL RPC client application.
IDMS/DC with standard linkage calling convention z/OS (4) Use this option if you want to build an IDMS/DC client application that calls the client interface object(s) with a standard linkage interface for IDMS/DC. Follow the steps under Using the COBOL Wrapper for IDMS/DC with Call Interfaces (z/OS). The module has a call interface to your COBOL RPC client application.
Micro Focus with standard linkage calling convention UNIX (4), Windows (4) Use this option if you want to build a Micro Focus client application that calls the client interface object(s) with a standard linkage interface. Follow the steps under Using the COBOL Wrapper for Micro Focus (UNIX and Windows). The module has a call interface to your COBOL RPC client application.

Notes:

  1. The generic RPC service module depends on target environment (CICS, Batch...), interface type and operating system (z/OS, z/VSE...). Using the wrong module leads to unpredictable results. Except for the interface type "CICS with DFHCOMMAREA calling convention" we recommend you use the generic RPC service module generated by the EntireX Workbench for a scenario as described under note 5.
  2. For z/VSE (see Installing EntireX under z/VSE), the generic RPC service modules are provided with names that are different from COBSRVI. See Delivered Modules for z/VSE.
  3. For IBM i, the generic RPC service module is provided with a name different from COBSRVI. See Delivered Modules for IBM i. Do not use this module; it is out of date. Generate the generic RPC service module as described under note 5.
  4. No generic RPC service module is delivered directly with the installation for this environment and/or operating system. Generate the generic RPC service module as described under note 5.
  5. Generating the generic RPC service module COBSRVI for a scenario is described under Generate Generic RPC Service Module COBSRVI.

Customize Automatically Generated Client Names

If you open the link Customize automatically generated Client Names on the Properties page you can adapt the names for the COBOL client interface objects (subprograms). When you call the page the first time, COBOL names are suggested based on the IDL program (program-definition) or IDL program alias names. The page varies, depending on whether the target COBOL environment supports long COBOL names or not:

z/OS and z/VSE

Max. 8 characters (short names) are supported as COBOL names:

graphics/using-generate_props_clientNames_zos-vse.png

Note:
If your IDL file contains more than one IDL library, the additional column IDL Library is displayed.

IBM i

Customization of client names for IBM i is the same as for z/OS and z/VSE. See z/OS and z/VSE.

UNIX and Windows with Micro Focus

Max. 31 characters are supported as COBOL names. By default, names are generated with a maximum of 8 characters (short names).

graphics/using-generate_props_clientNames_microFocus.png

Notes:

  1. If your IDL file contains more than one IDL library, the additional column IDL Library is displayed.
  2. With the check box Restrict the length of names to 8 characters you can flip between short names and long names. Both sorts of names (short and long) are stored in the property file. For generation you have to decide if short or long names are to be used.

BS2000

Max. 30 characters are supported as COBOL names. By default, names are generated with a maximum of 8 characters (short names).

graphics/using-generate_props_clientNames_bs2.png

Notes:

  1. If your IDL file contains more than one IDL library, the additional column IDL Library is displayed.
  2. With the check box Restrict the length of names to 8 characters you can flip between short names and long names. Both sorts of names (short and long) are stored in the property file. For generation you have to decide if short or long names are to be used.

Starting COBOL Level for Data Items in Generated Copybooks

With this option you can specify the starting COBOL level used in the generated copybooks for COBOL data items.

See Using the Generated Copybooks for syntax examples.

Specify a valid COBOL level in the range 1-49. The COBOL programming language maximum of 49 subtracted by the specified level must provide enough levels to hold all IDL levels. Note that IDL types may consume more than one COBOL level, for example:

  • IDL unbounded groups require a COBOL level for every dimension. If they are defined on IDL level 1, an extra COBOL level is required

  • IDL unbounded arrays require a COBOL level for every dimension plus one extra COBOL level

  • some basic (scalar) IDL data types need extra COBOL levels

Notes:

  1. Do not specify a level too deep because you may exceed the COBOL programming language maximum of 49 and the generated copybook cannot be compiled.
  2. For compatibility with Client and Server Examples for z/OS CICS, the level must be 3 or above.
  3. For compatibility with all other delivered examples, the level must be 2 or above.

RPC Communication Area

The RPC communication area is used to specify parameters that are needed to communicate with the broker and are not specific to client interface objects. These are for example the broker ID, client parameters such as userID and password and the server address such as class/servername/service etc.

Value Description
External Clause The RPC communication area is provided as a global area to the RPC client application and the generated client interface object(s). For more information, see option External Clause under Using the RPC Communication Area with a Standard Call Interface. The COBOL external clause is an extension to COBOL 85 standards and might not be supported by every COBOL compiler. Check your COBOL compiler documentation.
Linkage Section The RPC communication area is provided via an additional parameter between your RPC client application and the generated client interface object(s). For more information, see option Linkage Section under Using the RPC Communication Area with a Standard Call Interface and Using the RPC Communication Area with EXEC CICS LINK.
Copybook The RPC communication area is provided inside the generated client interface object(s). It is not visible in the RPC client application. Default values are retrieved from EntireX workbench preferences or IDL-specific properties and can be overwritten in the copybook COBINIT (see folder include). For more information, see option Copybook under Using the RPC Communication Area with a Standard Call Interface.

Generate Generic RPC Service Module COBSRVI

The generic RPC service module COBSRVI can be optionally generated in the folder client in the container folder. It contains functions needed for RPC communication where a client interface object(s) is not needed. See Generic RPC Services Module under Introduction to the COBOL Wrapper. The module depends on target environment (CICS, Batch...), client interface type (see Client Interface Types) and operating system (z/OS, z/VSE...). Using the wrong module leads to unpredictable results. Use this option to control the generation of this module. See Delivered Modules.

Handling depends on the interface type:

  • CICS with DFHCOMMAREA calling convention
    The module COBSRVI with the EXEC CICS LINK interface is already installed as a separate CICS program during installation (see Installing EntireX under z/OS | z/VSE).

    • Clear this option if you want to use the version already installed in CICS. This prevents the generation of the generic RPC service module. See Delivered Modules for z/OS | z/VSE.

    • Check this option if you want to replace the installed version in CICS with the version generated by the COBOL Wrapper. This makes sense if you need an update of the generic RPC service module because of a newer COBOL Wrapper version (Eclipse update without mainframe update).

  • All other calling conventions

Customize Automatically Generated Server Names

If you open the link Customize automatically generated Server Names on the properties page you can, adapt the names for the COBOL server (subprograms). When you call the page the first time, COBOL names are suggested based on the IDL program (program-definition) or IDL program alias names. For further details on customizing names for the server side, see the platform-specific section under Customize Automatically Generated Client Names; the information here also applies to server names:

Notes:

  1. Customization of server names is not supported under IBM i.
  2. If the server names (automatically generated or customized) differ from the IDL program names, a server mapping file is required. A server mapping file is an EntireX Workbench file with extension .svm or .cvm. It is generated during generation of RPC server and has to be used in subsequent steps. See Server Mapping Files for COBOL and Using the COBOL Wrapper for the Server Side.

Server Interface Types

Interface Type Target Operating System Description
CICS with DFHCOMMAREA calling convention z/OS, z/VSE Use this option if you want to build a CICS RPC server application with a DFHCOMMAREA interface. Follow the steps under Using the COBOL Wrapper for CICS with DFHCOMMAREA Calling Convention (z/OS and z/VSE).
CICS with Channel Container calling convention z/OS Use this option if you want to build a CICS RPC server application with a channel container interface. To specify a channel name, see Channel Name. Follow the steps under Using the COBOL Wrapper for CICS with Channel Container Calling Convention (z/OS).
CICS with DFHCOMMAREA large buffer interface z/OS, z/VSE Use this option if you want to build a CICS RPC server application with a large buffer interface. Follow the steps under Using the COBOL Wrapper for CICS with DFHCOMMAREA Large Buffer Interface (z/OS and z/VSE).
Batch with standard linkage calling convention z/OS, z/VSE, BS2000, IBM i Use this option if you want to build an application for an RPC server for Batch. Follow the steps under Using the COBOL Wrapper for Batch (z/OS, BS2000, z/VSE and IBM i).
IMS BMP with standard linkage calling convention z/OS Use this option if you want to build an IMS RPC server application for IMS BMP mode (no MPP) with standard call interfaces. If your server uses PCB pointers, see IMS PSB List below. Follow the steps under Using the COBOL Wrapper for IMS BMP (z/OS).
Micro Focus with standard linkage calling convention UNIX, Windows Use this option if you want to build an RPC server application for Micro Focus with standard linkage interface(s). Follow the steps under Using the COBOL Wrapper for Micro Focus (UNIX and Windows).

IMS PSB List

IMS PSB List applies to the server interface type "IMS BMP with standard linkage calling convention" only. If your server uses PCB pointers and requires that they are passed through the linkage section, an IMS PSB list is required. Your IDL must comply with the rules under IMS PCB Pointer IDL Rules. If no PCB pointers are required, omit the IMS PSB list. See Server Interface Types for more information.

Channel Name

Channel Name applies to the server interface type "CICS with Channel Container calling convention" only.

If a channel name is specified, the server is

  • called with the given channel name

  • generated with COBOL code to check for channel name validity.

If no channel name is specified, the server is

  • called with the "EntireXChannel" channel name

  • generated without COBOL code to check for channel name validity.

Your IDL must comply with the rules described under CICS Channel Container IDL Rules. See Server Interface Types for more information.

Generation Settings - Preferences

Use the Preferences page of the COBOL Wrapper to set the workspace defaults for the target operating system, interface types etc. The settings (except Type of COBOL mapping) are used as the defaults for the IDL properties when a new IDL file is created; see Generation Settings - Properties.

graphics/using-generate_prefs-cobWrapper.png

Use the Preferences > COBOL to set the workspace defaults for the COBOL mapping type. IDL Extractor for COBOL and COBOL Wrapper use this setting.

graphics/using-generate_prefs-cob.png

Every EntireX Workbench (Eclipse) workspace is either in client-side mapping mode (generating EntireX Workbench server mapping files with extension .cvm) or server-side mapping mode (generating EntireX Workbench server mapping files with extension .svm). See Server Mapping Files for COBOL for an introduction. The following rules apply:

For a description of all other preferences, see Generation Settings - Properties.