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 following:

  • The include folder contains the following:

    • the associated copybooks

    • the RPC communication area copybook ERXCOMM

    • optionally its extension copybook ERXVSTR

    • optionally the copybooks COBINIT and COBEXIT

    For further information on the usage of copybooks generated in this folder, see Using the Generated Copybooks.

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

    • 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 Designer 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 More Information Notes
CICS with DFHCOMMAREA Calling Convention z/OS, z/VSE Follow the steps under Using the COBOL Wrapper for CICS with DFHCOMMAREA Calling Convention (z/OS and z/VSE). 1
CICS with Standard Linkage Calling Convention z/OS, z/VSE Follow the steps under Using the COBOL Wrapper for CICS with Call Interfaces (z/OS and z/VSE). 2
Batch with Standard Linkage Calling Convention z/OS, z/VSE, BS2000, IBM i Follow the steps under Using the COBOL Wrapper for Batch (z/OS, BS2000, z/VSE and IBM i). 2
IMS BMP with Standard Linkage Calling Convention z/OS Follow the steps under Using the COBOL Wrapper for IMS (z/OS). 2
IMS MPP with Standard Linkage Calling Convention z/OS Follow the steps under Using the COBOL Wrapper for IMS (z/OS). 2
IDMS/DC with Standard Linkage Calling Convention z/OS Follow the steps under Using the COBOL Wrapper for IDMS/DC with Call Interfaces (z/OS). 2
Micro Focus with Standard Linkage Calling Convention UNIX, Windows Follow the steps under Using the COBOL Wrapper for Micro Focus (UNIX and Windows). 2

Notes:

  1. Use this option if you want to build a CICS RPC client application that calls the client interface object(s) and the generic RPC module COBSRVI with a DFHCOMMAREA interface.
  2. Use this option if you want to build an RPC client application that calls the client interface object(s) and the generic RPC module COBSRVI with a standard linkage interface.

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 copybook ERXCOMM and its extension ERXVSTR are 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 Notes
External Clause This kind of RPC communication area usage applies to the scenarios CICS | Batch | IMS | Micro Focus. The RPC communication area copybooks are defined in the working storage section as COBOL data items with the EXTERNAL clause in the RPC client application. They are passed with the EXTERNAL clause to and the generated client interface object(s). 1
Linkage Section This kind of RPC communication area usage applies to the scenarios CICS | Batch | IMS | Micro Focus. The RPC communication area copybooks are defined in the working storage section as COBOL data items. They are passed via additional parameter between your RPC client application and the generated client interface object(s). 2
Copybook This kind of RPC communication area usage is available in the z/OS operating system and Micro Focus environments. Refer to the scenarios CICS | Batch | IMS | Micro Focus. The RPC communication area copybooks are provided inside the generated client interface object(s). It is not visible in the RPC client application - it is local to the client interface objects. Default values are retrieved from Designer preferences or IDL-specific properties and can be overwritten in the copybook COBINIT (see folder include). 2

Notes:

  1. The client interface objects are statically linked to the RPC client. It is not possible to call them dynamically.
  2. The client interface objects can be statically linked or called dynamically. For IBM compilers, refer to documentation on the DYNAM compiler option; for other compilers, to your compiler documentation.

Generation and Usage of Generic RPC Service Module COBSRVI

The generic RPC service module COBSRVI can be optionally generated in the folder client in the container folder. It acts as a runtime for RPC communication. 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...). Use this option to control the generation of this module.

Handling depends on the interface type:

  • CICS with DFHCOMMAREA calling convention
    For this interface type, the generic RPC service module is installed once within CICS as a CICS program and shared by all RPC clients using this interface type. Details and the architecture of this scenario are described under Using the COBOL Wrapper for CICS with DFHCOMMAREA Calling Convention (z/OS and z/VSE).

    • Check this option if you want to install or replace the installed generic RPC service module in CICS with the version generated by the COBOL Wrapper. This makes sense in the following situations:

      • You have not installed the RPC examples on z/OS, because installation of this module is part of Installing RPC Examples.

      • You need an update of the generic RPC service module because of a newer COBOL Wrapper version, for example an Eclipse update without mainframe update. For compile job and CICS CSD definitions see Delivered Modules for z/OS | z/VSE.

    • Clear this option if you have already installed the generic RPC service module in CICS (already installed RPC examples for z/OS or previous COBOL Wrapper project) and do not want to re-install it in CICS. This prevents the generation of the generic RPC service module.

  • All other calling conventions

    • The preferred approach is to check this option. This will generate the generic RPC service module. The generated module is part of your client application. Its usage is described under Using the COBOL Wrapper with a Call Interface (CICS | Batch | IMS | Micro Focus).

    • Clear this option if you can reuse the generic RPC service module from a previous COBOL Wrapper project. This will prevent the generation of the generic RPC service module. It is important that Target Operating System, Client Interface Types and Characters Used for String Literals are the same.

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 a Designer 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 Designer (Eclipse) workspace is either in client-side mapping mode (generating Designer server mapping files with extension .cvm) or server-side mapping mode (generating Designer 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.