Version 9.5 SP1
 —  EntireX COBOL Wrapper  —

Generate 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 Generate COBOL from Software AG IDL > RPC Client and RPC Server to generate the COBOL source files.

graphics/cobWrapper_generateCobol.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:

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

Top of page

Generation Settings - Properties

This section covers the following topics:

Introduction

To set properities for COBOL Wrapper generation, use the Properties wizzard of the IDL file. The target operating system (Target OS) 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. Whether file extensions are generated or not depends on the operating system (Target OS).

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/OSD operating system.
IBM i IBM 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 Description RPC Communication Area Usage
CICS with DFHCOMMAREA calling convention z/OS, z/VSE 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 RPC communication area is passed as described in Using the RPC Communication Area with EXEC CICS LINK. See also RPC Communication Area.
CICS with standard linkage calling convention z/OS, z/VSE 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 RPC communication area is passed with one of the options as described in Using the RPC Communication Area with a Standard Call Interface. See also RPC Communication Area.
Batch with standard linkage calling convention z/OS, z/VSE, BS2000/OSD, IBM i 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/VSE, IBM i, BS2000/OSD and z/OS).
IMS BMP with standard linkage calling convention z/OS 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).
IMS MPP with standard linkage calling convention z/OS 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).
IDMS/DC with standard linkage calling convention z/OS 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).
Micro Focus with standard linkage calling convention UNIX, Windows 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).

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/OSD

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:

Notes:

  1. Do not specifiy 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 for Module COBSRVI

The generic RPC service module COBSRVI is generated in the folder client. See Generic RPC Services Modules. Use this option to control the generation of this module.

If you are using the COBOL Wrapper for the first time:

If you are an experienced user of the COBOL Wrapper:

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:

Note:
Customization of server names is not supported under IBM i.

If the server names (automatically generated or customized) differ from the IDL program names, a server-side server mapping (SVM) file is required. It is generated during generation of RPC server and has to be used in subsequent steps (deployed to an EntireX RPC Server or wrapped into an EntireX Adapter). See Select an IDL File and Generate RPC Client or RPC Server under Generate COBOL Source Files from Software AG IDL Files.

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/OSD, IBM i Use this option if you want to build a batch RPC server application. Follow the steps under Using the COBOL Wrapper for Batch (z/OS, IBM i, BS2000/OSD and z/VSE).
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 a Micro Focus RPC server application 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

If no channel name is specified, the server is

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

Top of page

Generation Settings - Preferences

graphics/using-generate_prefs.png

The workspace defaults for the target operating system, interface types for clients and server etc. are set in the Preferences page of the COBOL Wrapper. For a description, see Generation Settings - Properties.

Top of page