This document describes how to generate COBOL source files from Software AG IDL files. It covers the following topics:
From the context menu, choose > and to generate the COBOL source files.
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 Generic RPC Services Modules.
The folder include containes the associated
copybooks, the RPC communication area copybook ERXCOMM and
optionally the copybooks COBINIT and COBEXIT.
Notes:
COBSRVI is only
generated if the option Generate Generic RPC Service Module
COBSRVI is set, see Generate Generic RPC Service for Module COBSRVI.
ERXCOMM , see Using the RPC Communication Area.
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 implementation skeletons.
 |
Warning: Take care not to overwrite an existing server implementation with a server skeleton. We recommend moving your server implementation to a different folder. |
If an SVM file was generated, you are promted with instructions on how to provide it to the server:
For RPC servers, you have to deploy it either by using a wizard or a manual approach, depending on the specific RPC server used. See Server Mapping Deployment.
For the EntireX Adapter, it is picked up automatically together with the IDL file when the adapter connection is generated. For further information, see the latest version of the EntireX Adapter under https://empower.softwareag.com/Products/Documentation/default.asp.
This section covers the following topics:
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).
In the following, we give a detailed description of the properties that need to be set for each type of generation:
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. |
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. |
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 .
| 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). |
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:
Max. 8 characters (short names) are supported as COBOL names:
Note:
If your IDL file contains more than one IDL library, the additional column IDL Library is displayed.
Customization of client names for IBM i is the same as for z/OS and z/VSE. See z/OS and z/VSE.
Max. 31 characters are supported as COBOL names. By default, names are generated with a maximum of 8 characters (short names).
Notes:
Max. 30 characters are supported as COBOL names. By default, names are generated with a maximum of 8 characters (short names).
Notes:
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 unboundend 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:
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.
|
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:
Clear this option for interface type "CICS with DFHCOMMAREA calling convention". The generic RPC server module will not be generated, which will speed up generation time. The generic RPC server module is not needed because it is already installed with your z/OS and z/VSE mainframe installation.
Check this option for all other interface types to generate the generic RPC server module.
If you are an experienced user of the COBOL Wrapper:
Clear this option if you can reuse the generic RPC server module from a previous COBOL Wrapper project. This will speed up generation time. It is important that Target Operating System, Client Interface Types and Characters Used for String Literals are the same.
Check this option if you need an update of the generic RPC server module because of a newer COBOL Wrapper version (Eclipse update without mainframe installation) to generate the generic RPC server module.
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.
| 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 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 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.
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.
