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 Delivered Modules.
The folder include contains 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 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 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.
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:
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.
Check the option Synchronize with server-side mapping container now for the following RPC servers:
z/OS (CICS, Batch, IMS) | Micro Focus | BS2000 | z/VSE (CICS, Batch).
This calls the Deployment Wizard. See Server Mapping Deployment Wizard in the Designer documentation. If you are using the Server Mapping Deployment Wizard for first time with no predefined deployment environment preferences, continue with Step 2a: Create a New Deployment Environment in the Designer documentation. If deployment environments are already defined, you may also continue with Step 3: Select and Existing Deployment Environment and Deploy.
Uncheck the option Synchronize with server-side mapping container now.
For EntireX Adapter
You need to update your generated IS adapter as described under To update an existing connection in section Step 3: Create or Update an Adapter Connection in the Integration Server Wrapper documentation.
For CICS ECI and IMS Connect RPC servers
Continue as described under Deploying Server-side Mapping Files to the Wrapper (CICS ECI | IMS Connect).
For later synchronization of the RPC servers
See Deploying Server-side Mapping Files in the RPC server documentation for z/OS (CICS,
Batch,
IMS) |
Micro Focus |
CICS ECI |
IMS Connect |
BS2000 |
z/VSE (CICS |
Batch)
To quit the COBOL Wrapper and deploy the server-side mapping file
Check the option Synchronize with server-side mapping container now and choose . This calls the Deployment Wizard. See Server Mapping Deployment Wizard in the Designer documentation.
If you are using the Server Mapping Deployment Wizard for first time with no predefined deployment environment preferences, continue with Step 2a: Create a New Deployment Environment in the Designer documentation.
If deployment environments are already defined, you may also continue with Step 3: Select and Existing Deployment Environment and Deploy.
Continue with Using the COBOL Wrapper for the Server Side.
To quit the COBOL Wrapper without deploying the server-side mapping file
Clear the option Synchronize with server-side mapping container now and choose .
Synchronize the server-side mapping container of the target RPC server later. See Deploying Server-side Mapping Files in the RPC server documentation for z/OS (CICS, Batch, IMS) | Micro Focus | CICS ECI | IMS Connect | BS2000 | z/VSE (CICS | Batch).
For the webMethods EntireX Adapter for Integration Server and IMS Connect or CICS ECI connections, update your Adapter connection. See Step 3: Create or Update an Adapter Connection in the Integration Server Wrapper documentation.
Continue with Using the COBOL Wrapper for the Server Side.
This section covers the following topics:
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.
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 operating system. |
| IBM i | 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 | 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:
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:
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 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:
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 Designer 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 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).
The preferred approach is to check this option. This will generate the generic RPC service module.
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.
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:
| 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 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.
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.
Use the Preferences > COBOL to set the workspace defaults for the COBOL mapping type. IDL Extractor for COBOL and COBOL Wrapper use this setting.
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:
Server mapping files are generated automatically for RPC servers if required. See When is a Server Mapping File Required? for the COBOL Wrapper in the Software AG Designer documentation.
Server mapping files are not generated for RPC clients.
For a description of all other preferences, see Generation Settings - Properties.