• Step 1: Start the IDL Extractor for COBOL Wizard

• Step 2: Select a COBOL Extractor Environment or Create a New One

• Step 3: Select the COBOL Source

• Step 4: Define the Extraction Settings and Start Extraction

• Step 5: Select the COBOL Interface and Map to IDL Interface

• Step 6: Finish the Mapping Editor

• Step 7: Validate the Extraction and Test the IDL File

---

Step 1: Start the IDL Extractor for COBOL Wizard

To continue, press Next and continue with Step 2: Select a COBOL Extractor Environment or Create a New One.

Step 2: Select a COBOL Extractor Environment or Create a New One

If no COBOL extractor environments are defined, you only have the option to create a new environment. An IDL Extractor for COBOL environment provides defaults for the extraction and refers to COBOL programs and copybooks that are

• stored locally on the same machine where the Designer is running: a local COBOL extractor environment

or

• stored remotely on a host computer: a remote COBOL extractor environment. The extractor service is required to access COBOL programs and copybooks remotely with a remote COBOL extractor environment. The extractor service is supported on platforms z/OS and BS2000. See Extractor Service in the RPC Server documentation for Batch | IMS | BS2000.

This page offers the following options:

To select an existing local COBOL extractor environment

1. Check radio button Choose an existing COBOL extractor environment and select a local COBOL extractor environment.

2. Continue with Step 3: Select the COBOL Source below.

To select an existing remote COBOL extractor environment

1. Check radio button Choose an existing COBOL extractor environment and select a remote COBOL extractor environment.

2. Continue with Step 3: Select the COBOL Source below.

To create a new local COBOL extractor environment

1. Check radio button Create a new COBOL extractor environment.

2. Follow the instructions in the Preferences section under Create New Local Extractor Environment (z/OS, BS2000, z/VSE and IBM i).

3. Continue with Step 3: Select the COBOL Source below.

To create a new remote COBOL extractor environment

1. Check radio button Create a new COBOL extractor environment.

2. Follow the instructions in the Preferences section under Create New Remote Extractor Environment z/OS | BS2000.

3. Continue with Step 3: Select the COBOL Source below.

Step 3: Select the COBOL Source

Selecting the COBOL source is different depending on whether the COBOL source is stored locally on the same machine where the Software AG Designer is running, or on a remote host computer.

• Selecting a COBOL Source Stored Locally

• Selecting a Member from a Partitioned Data Set on Remote Host (z/OS)

• Selecting a Member from a CA Librarian Data Set on Remote Host (z/OS)

• Selecting a Member Archive Level from a CA Librarian Data Set on Remote Host (z/OS)

• Selecting an Element (S) from an LMS Library on Remote Host (BS2000)

Selecting a COBOL Source Stored Locally

In step 2 above you selected or created a local extractor environment for z/OS. If you select a local COBOL extractor environment, you can browse for the COBOL program in the local file system. If you selected the COBOL source file before you started the wizard, and do not have a directory defined in the preferences of your Local Extractor Environment, the file location is already present. See Create New Local Extractor Environment (z/OS, BS2000, z/VSE and IBM i). To browse for the COBOL source file, choose Browse.

Selecting a Member from a Partitioned Data Set on Remote Host (z/OS)

In step 2 above you selected or created a remote extractor environment. The following page offers all data sets starting with the high-level qualifier defined in the Filter Settings of the remote extractor environment. See Creating a New Remote Extractor Environment (z/OS) under COBOL Preferences.

Select the partitioned data set from which you want to extract and choose Next. Proceed depending on the selected data set type. See Selecting a Member from a Partitioned Data Set on Remote Host (z/OS).

The following page offers all members contained in the partitioned data set selected in the previous step, starting with the member name prefix defined in the Filter Settings of the remote extractor environment. See Define the remote extractor environment under COBOL Preferences.

Select the member from which you want to extract. You can select only one COBOL source. The source can be a COBOL program or a COBOL copybook.

Choose Next and continue with Step 4: Define the Extraction Settings and Start Extraction below.

Selecting a Member from a CA Librarian Data Set on Remote Host (z/OS)

In step 2 above you selected or created a remote extractor environment. The following page offers all data sets starting with the high-level qualifier defined in the Filter Settings of the remote extractor environment. See Creating a New Remote Extractor Environment (z/OS) under COBOL Preferences.

Select the CA Librarian data set from which you want to extract and choose Next. Proceed depending on the selected data set type. See Selecting a Member from a CA Librarian Data Set on Remote Host (z/OS).

The following page offers all members contained in the CA Librarian data set selected in the previous step, starting with the member name prefix defined in the Filter Settings of the remote extractor environment. See Define the remote extractor environment under COBOL Preferences.

You can select only one COBOL source. The source can be a COBOL program or a COBOL copybook. If you want to extract from

• the latest (current) version of the member, select the member, choose Next and continue with Step 4: Define the Extraction Settings and Start Extraction below.

• a previous (archived) version of the member, check the box Show the Archive Levels of the selected member, select the member, choose Next and continue with Selecting a Member Archive Level from a CA Librarian Data Set on Remote Host (z/OS).

Selecting a Member Archive Level from a CA Librarian Data Set on Remote Host (z/OS)

The following page offers all archive levels of the previously selected member.

Select the member from which you want to extract. You can select only one archive level. Choose Next and continue with Step 4: Define the Extraction Settings and Start Extraction below.

Selecting an Element (S) from an LMS Library on Remote Host (BS2000)

In step 2 above you selected or created a remote extractor environment.

The following page offers all data sets starting with the high-level qualifier defined in the Filter Settings of the remote extractor environment. See Creating a New Remote Extractor Environment (BS2000) under COBOL Preferences.

The following page offers all elements contained in the LMS library selected in the previous step, starting with the member name prefix defined in the Filter Settings of the remote extractor environment. See Define the remote extractor environment under COBOL Preferences.

Select the element from which you want to extract. You can select only one COBOL source. The source can be a COBOL program or a COBOL copybook.

Choose Next and continue with Step 4: Define the Extraction Settings and Start Extraction below.

Step 4: Define the Extraction Settings and Start Extraction

In this page you specify the COBOL source and Software AG IDL target options used for IDL extraction.

• Operating System

• Interface Type

• Software AG IDL File

• COBOL to IDL Mapping

Operating System

The operating system is already defined in the extractor environment in the IDL Extractor for COBOL preferences, see COBOL Preferences.

Interface Type

The interface type must match the type of your COBOL server program. It is used by the RPC server and the EntireX Adapter at runtime to correctly call the COBOL server and must be a supported interface type of the EntireX runtime component used. See Compatibility between COBOL Interface Types and RPC Server.

Additional information may be required depending on the interface type:

• CICS with DFHCOMMAREA Calling Convention
  Specify Input Message same as Output Message. If the COBOL server program uses a different COBOL output data structure compared to its input data structure, that is, the input message layout is overlaid with another layout on output, you need to uncheck Input Message same as Output Message. See the following COBOL server examples:

  • Example 1: Redefines

  • Example 2: Buffer Technique

  • Example 3: COBOL SET ADDRESS Statements

  If the COBOL server program uses the same COBOL data structure on input as well as on output, you need to check Input Message same as Output Message. See the following COBOL server examples:

  • Example 1: Redefines

  • Example 2: Buffer Technique

  • Example 3: COBOL SET ADDRESS Statements

• CICS with Channel Container Calling Convention
  Optionally, specify a channel name. See Extracting from a CICS Channel Container Program.

• CICS with DFHCOMMAREA Large Buffer Calling Convention
  Specify Input Message same as Output Message. If the COBOL server program uses a different COBOL large output buffer data structure compared to its large input buffer data structure, you need to uncheck Input Message same as Output Message. See CICS with DFHCOMMAREA Large Buffer Interface (In same as Out, In different to Out).

• COBOL Converter
  Specify Input Message same as Output Message. If a different COBOL output data structure compared to its input data structure is used (that is, the input message layout is overlaid with another layout on output) you need to uncheck Input Message same as Output Message. See COBOL Converter (In same as Out, In different to Out).

• IMS MPP Message Interface (IMS Connect)
  Specify how you want the transaction name to be determined. See Extracting from an IMS MPP Message Interface Program.

• IMS BMP with Standard Linkage Calling Convention
  You can optionally set the IMS PSB List. See Extracting from an IMS BMP Standard Call Interface.

• Batch with Standard Linkage Convention
  No further information is required.

For an introduction to interface types, see Supported COBOL Interface Types.

Software AG IDL File

With the Software AG IDL file target options you specify the IDL file and IDL library names used:

• File name specifies the file name used by the operating system.

• Modify existing file is enabled only when the IDL file already exists. If enabled, check this option to continue the extraction.

• Library name defines the IDL library name used in the IDL file. The dialog box cannot be edited when you modify an existing IDL file. If there are multiple libraries, you can select one of these; if there is only one library, the box is disabled. When you extract the IDL the first time or you specify the name of an existing IDL file, the box can be edited (like a text widget). If you specified an existing IDL file, the currently existing library names are available in the box.

• Container specifies the eclipse container used for the IDL file

COBOL to IDL Mapping

With these target options you specify how COBOL data items are mapped to IDL. You can turn fixed length COBOL data types into variable length data types. This is useful if connecting COBOL to endpoints with a concept of string types - such as Java, .NET, C, XML, web services etc. Real strings without trailing blanks are received. It also reduces the messages size of RPC requests.

• With a mapping to Strings with variable length ⁽¹⁾, the transfer of data in the RPC data stream depends on the actual length of the data and not the field size, as seen in COBOL. For the COBOL side, the actual content length of such fields is determined using a trim mechanism.

  For PIC X, A and G, all trailing SPACEs are ignored before send. After receive, the content is padded with trailing SPACEs up to the COBOL field size.

  For PIC N ⁽³⁾, the Unicode code point U+0020 is used for trimming and padding.

  If your application relies on trailing SPACEs or Unicode code points U+0020, you cannot use a mapping to strings with variable length ⁽¹⁾. Use strings with fixed length ⁽²⁾ instead.

• With a mapping to Strings with fixed length ⁽²⁾, no trimming takes place. If the mapping in the calling endpoint calling COBOL is a variable length string data type, in most cases you will receive trailing SPACEs or trailing Unicode code points U+0020 respectively.

• Check the box Map FILLER fields to IDL if COBOL FILLER pseudo-parameters are to be part of the RPC client interface. By default they are not mapped to IDL.

Notes:

1. Technically, a mapping to Strings with variable length forces IDL types AVn, KVn or UVn to be extracted. See also the notes under IDL Data Types in the IDL Editor documentation.

2. Technically, a mapping to Strings with fixed length the IDL types An, Kn or Un. See also the notes under IDL Data Types in the IDL Editor documentation.

Choose Next and start the extraction. The wizard now analyzes the COBOL program. During this process the following situations are possible:

• Referenced copybooks cannot be found. In this case the wizard prompts you for every missing copybook. Continue with optional step Step 4.1x: Copybook Cannot be Found - Local Extraction | Remote Extraction (z/OS) | Remote Extraction (BS2000) depending on your situation.

• If referenced copybooks are not available, you can choose Ignore or Ignore All, a copybook status summary page is displayed, see Step 4.2: Copybook Status Summary (Optional).

• No COBOL program ID can be located if you extract, for example, from a copybook that contains COBOL data items only. In this case, the wizard prompts you to enter the COBOL program ID. Continue with Step 4.3: Enter COBOL Program ID (Optional).

• There is no copybook reference in your COBOL source or all referenced copybooks are found. Also the COBOL program ID can be located or is not needed as for interface type COBOL Converter. In this case continue with Step 5: Select the COBOL Interface and Map to IDL Interface under Scenario I: Create New IDL and Server Mapping Files.

Step 4.1a: Copybook Cannot be Found - Local Extraction

This dialog enables you to browse directories where missing copybooks might be found. If there are any specific copybook file extensions, you can define them here.

The copybook that cannot be found is given in the window, here its name is "ACPYBK21". In the extractor Preferences, the copybook directory that contains the copybook or the copybook file extension is not defined.

Continue with one of the following actions:

To ignore this copybook only

1. Choose Ignore and go back to Step 4: Define the Extraction Settings and Start Extraction.

2. Choose Next to start extraction again.

To ignore this and all further copybooks

1. Choose Ignore All and go back to Step 4: Define the Extraction Settings and Start Extraction.

2. Choose Next to start extraction again.

To complete the extractor environment

1. Choose Workspace or File System to browse for the copybook directory.

2. Check the copybook file extensions. Both will be saved in the COBOL extractor preferences and reused in further extractions.

3. Choose OK and go back to Step 4: Define the Extraction Settings and Start Extraction.

4. Choose Next to start extraction again.

Step 4.1b: Copybook Cannot be Found - z/OS Remote Extraction

This dialog enables you to browse remote locations (partitioned or CA Librarian data sets) where missing copybooks might be found.

The copybook that cannot be found is given in the window; here its name is "CUSTREC". In the extractor preferences, the copybook data set that contains the copybook is not defined.

Continue with one of the following choices:

To ignore this copybook only

1. Choose Ignore and go back to Step 4: Define the Extraction Settings and Start Extraction.

2. Choose Next to start extraction again.

To ignore this and all further copybooks

1. Choose Ignore All and go back to Step 4: Define the Extraction Settings and Start Extraction.

2. Choose Next to start extraction again.

To complete the extractor environment

1. Choose Find to browse for the copybook data set. It will be saved in the COBOL extractor preferences and reused in further extractions.

2. Choose OK and go back to Step 4: Define the Extraction Settings and Start Extraction.

3. Choose Next to start extraction again.

Step 4.1c: Copybook Cannot be Found - BS2000 Remote Extraction

This dialog enables you to browse remote locations (LMS libraries) where missing copybooks might be found.

The copybook that cannot be found is given in the window; here its name is "XTAB". In the extractor preferences, the copybook LMS library that contains the copybook is not defined.

Continue with one of the following choices:

To ignore this copybook only

1. Choose Ignore and go back to Step 4: Define the Extraction Settings and Start Extraction.

2. Choose Next to start extraction again.

To ignore this and all further copybooks

1. Choose Ignore All and go back to Step 4: Define the Extraction Settings and Start Extraction.

2. Choose Next to start extraction again.

To complete the extractor environment

1. Choose Find to browse for the copybook LMS library. It will be saved in the COBOL extractor preferences and reused in further extractions.

2. Choose OK and go back to Step 4: Define the Extraction Settings and Start Extraction.

3. Choose Next to start extraction again.

Step 4.2: Copybook Status Summary (Optional)

This summary page lists all COBOL copybooks which were not available during extraction.

• If any relevant COBOL data item describing the server interface is contained in one of the listed copybooks, you cannot continue. Terminate the extraction and try to get the missing copybooks.

• If no relevant COBOL data item describing the server interface is contained in the copybooks, you can continue. Choose OK.

Step 4.3: Enter COBOL Program ID (Optional)

This page is shown whenever the program ID of the COBOL source is missing. Entering a COBOL program name is compulsory.

No COBOL program ID can be located if you extract, for example, from a copybook that contains COBOL data items only. The COBOL program ID

• is the COBOL program name

• is often the name of the executable or load module

• can be found in the IDENTIFICATION DIVISION (abbreviated to"ID" ). Example

  ID DIVISION.
  PROGRAM-ID.   CUSTINFO.
  AUTHOR.       BMF.
  DATE-WRITTEN. 26-11-1996

To complete the extraction

1. Enter the COBOL program ID.

2. Choose OK to continue with Step 5: Select the COBOL Interface and Map to IDL Interface.

Step 5: Select the COBOL Interface and Map to IDL Interface

A COBOL source program mostly does not contain all the information needed for IDL mapping. With the Mapping Editor you enter this missing information. In general, mapping the COBOL data items to IDL with the Mapping Editor is a two-step process:

1. First, select the COBOL data items of the COBOL interface.

2. Then map the COBOL interface to the IDL interface. Define

   • which COBOL data items are mapped to IDL (Select REDEFINE paths, Suppress Unneeded COBOL Data Items)

   • the direction of the COBOL data items (Map to [In, Out, InOut])

   • field values for COBOL data items that are not sent by clients to the COBOL server (Set COBOL Data Items to Constant)

   • COBOL server with multiple functions (Map to Multiple IDL Interfaces)

   • COBOL server output depends on COBOL input (Map to Multiple IDL Interfaces)

   • COBOL server with conditional output (Set Multiple Possible Output (MPO) Structures)

   • COBOL table usage (Set Array Mapping (fixed <-> unbounded))

   • COBOL data items mapped to binary (Map to Binary, Revert Binary Mapping)

   • etc.

See the guidelines on IDL Extraction per Interface Type for the COBOL Mapping Editor or by COBOL syntax in User-defined Mapping under COBOL to IDL Mapping for further information on this important extraction step.

The outcome of the Mapping Editor is the IDL file and a server mapping file (optional). See When is a Server Mapping File Required? under Server Mapping Files for COBOL in the Designer documentation. Both files are written with the file name entered for the IDL file in Step 4: Define the Extraction Settings and Start Extraction.

Step 6: Finish the Mapping Editor

When you choose Save in the Mapping Editor, the IDL file is generated. If required, a server mapping file (.cvm) is generated, too.

Step 7: Validate the Extraction and Test the IDL File

The IDL file is used to build RPC clients using an EntireX Wrapper of your choice, or an IS adapter service using the Integration Server Wrapper.

If a server mapping file (.cvm) is extracted:

• You need to rebuild all existing RPC clients communicating with this RPC server program and re-generate the client interface objects.

• For existing IS adapters generated with the EntireX Adapter need to be updated. See Step 3: Create or Update an Adapter Connection in the Integration Server Wrapper documentation.

If you are using the RPC Server for CICS, before calling your extracted RPC server, check if you need to alter

• CICS settings, for example TWASIZE. See CICS Settings.

• For z/OS additionally IBM LE Runtime Options - for example AMODE24, how to trap ABENDs etc.

For a quick validation of your extraction (all interface types except COBOL Converter) you can

• use the IDL Tester to validate the extraction, see EntireX IDL Tester in the Designer documentation.

• generate an XML mapping file (XMM) and use the EntireX XML Tester for verification. See EntireX XML Tester in the XML/SOAP Wrapper documentation.