Scenario I: Create New IDL and Server Mapping Files

Step 1: Start the IDL Extractor for COBOL Wizard

graphics/selectWizard.png

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 EntireX Workbench 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/OSD. See Extractor Service in the z/OS Batch | IMS | BS2000/OSD Batch RPC Server documentation.

graphics/createNewEnv.png

This page offers the following options:

Start of instruction setTo 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.

Start of instruction setTo 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.

Start of instruction setTo 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, z/VSE, BS2000/OSD and IBM i) | Micro Focus (UNIX and Windows) in the IDL Extractor for COBOL documentation.

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

Start of instruction setTo 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/OSD in the IDL Extractor for COBOL documentation.

  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 EntireX Workbench is running, or on a remote host computer.

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, z/VSE, BS2000/OSD and IBM i) | Micro Focus (UNIX and Windows) in the IDL Extractor for COBOL documentation. To browse for the COBOL source file, choose Browse.

graphics/createNew_selectSource_local.png

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 Create New Remote Extractor Environment (z/OS) under IDL Extractor for COBOL Preferences.

graphics/selectSourceDataset.png

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 Step 3: Define the Remote Extractor Environment under IDL Extractor for COBOL Preferences.

graphics/selectSourceFromDataset.png

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 Create New Remote Extractor Environment (z/OS) under IDL Extractor for COBOL Preferences.

graphics/selectSourceDataset.png

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 Step 3: Define the Remote Extractor Environment under IDL Extractor for COBOL Preferences.

graphics/selectSourceFromCalib.png

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

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.

graphics/createNew_selectSource_remote-mal.png

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

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 Create New Remote Extractor Environment (BS2000/OSD) under IDL Extractor for COBOL Preferences .

graphics/selectFromRemote_bs2.png

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 Step 3: Define the Remote Extractor Environment under IDL Extractor for COBOL Preferences.

graphics/selectFromRemote_bs2_elements.png

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.

graphics/createNew_settings.png

Operating System

The operating system is already defined in the extractor environment in the IDL Extractor for COBOL preferences, see IDL Extractor for 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 RPC server used. See Compatibility between COBOL Interface Types and RPC Server.

Additional information may be required depending on the interface type:

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.

    For the interface type "Micro Focus with standard linkage calling convention" and if the COBOL server is an operating system standard library (.so|.sl on UNIX or .dll on Windows) or a Micro Focus proprietary library (*.lbr), the IDL library name used must match the operating system file name. For Micro Focus proprietary formats, intermediate code (*.int) and generated code (*.gnt), any IDL library name can be used. See Locating and Calling the Target Server in the Micro Focus RPC Server documentation.

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

  • If the target RPC clients support variable length strings without any restriction, we recommend you map alphanumeric fields to "Strings with variable length". This is true for most modern target environments such as Java, .NET, DCOM, C, Natural, SOAP, XML.

  • If the target RPC clients do not support variable length strings or support them with restrictions, we recommend you map alphanumeric fields to "Strings with fixed length"

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

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

graphics/copybookFlowchart.png

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.

graphics/createNew_settings_noCopybook-local.png

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:

Start of instruction setTo 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.

Start of instruction setTo 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.

Start of instruction setTo 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.

graphics/noCopybook_remote.png

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:

Start of instruction setTo 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.

Start of instruction setTo 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.

Start of instruction setTo 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/OSD Remote Extraction

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

graphics/createNew_settings_noCopybook-remote-bs2.png

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:

Start of instruction setTo 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.

Start of instruction setTo 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.

Start of instruction setTo 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.

graphics/createNew_settings_copybookStatusSummary.png

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

graphics/createNew_settings_noCobId.png

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

Start of instruction setTo 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)

    • multiple IDL interfaces (Map to Multiple IDL Interfaces)

    • etc.

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

graphics/createNew_selectParms.png

The outcome of the Mapping Editor is the IDL file and a server mapping file (optional). See When is a Server Mapping File Required? in the EntireX Workbench 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: Finishing the Mapping Editor

When you choose Save in the Mapping Editor, the IDL file is generated. If required, a server mapping file is generated,too. The server mapping file is either of type client-side (extension .cvm) or server-side (extension .svm). See How to Set the Type of Server Mapping Files.

  • If you are using client-side mapping files, continue with Step 7: Validate the Extraction and Test the IDL File.

  • If you are using server-side mapping files, the dialog below is displayed whenever the COBOL Mapping Editor is saved. There are two options to choose from:

    • Save IDL and server mapping files
      will save the generated files into the workspace and quit the COBOL Mapping Editor

      The generated server-side mapping file need to be synchronized with the server-side mapping container of the target RPC server, except for IMS Connect and CICS ECI connections with the EntireX Adapter, where they are wrapped into the Integration Server connection - 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:

      • Uncheck the option Synchronize with server-side mapping container now for

        • EntireX Adapter and IMS Connect and CICS ECI connections

        • the following RPC servers: CICS ECI | IMS Connect

        • later synchronization of other RPC servers

    • Extract additional COBOL program and append to the IDL and server mapping files
      will save the generated files into the workspace, quit the Mapping Editor and start the IDL Extractor for COBOL again. The additionally extracted COBOL source will then be added to the previously generated IDL and server mapping files.

graphics/createNew_finishMappingEditor.png

Start of instruction setTo save the generated files into the workspace, quit the Mapping Editor and deploy the server-side mapping file

  1. Select Save IDL and server mapping files.

  2. 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 EntireX Workbench documentation.

  3. Continue with Step 7: Validate the Extraction and Test the IDL File.

Start of instruction setTo save the generated files into the workspace and quit the Mapping Editor without deploying the server-side mapping file

  1. Select Save IDL and server mapping files.

  2. Clear the option Synchronize with server-side mapping container now and choose OK.

  3. Continue with Step 7: Validate the Extraction and Test the IDL File.

Start of instruction setTo save the generated files into the workspace, quit the Mapping Editor and start the IDL Extractor for COBOL again

Warning:
Do not edit the IDL file manually or with the IDL Editor, except for changing parameter names. Otherwise, consistency between the IDL file and the server mapping file will be lost, resulting in unexpected behavior. For this purpose use the COBOL Mapping Editor instead and choose Scenario III: Modify Existing IDL and Server Mapping Files.
Warning:
A server mapping file extracted this way must not be re-created by the COBOL Wrapper. Server mapping specifications of such a file would not be powerful enough to adequately describe your COBOL server program extracted here.

Step 7: Validate the Extraction and Test the IDL File

The IDL file is used to build RPC clients using an EntireX Workbench wrapper of your choice. See EntireX Wrappers in the EntireX Workbench documentation.

If you are using client-side mapping files:

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

  • For connections with the webMethods EntireX Adapter you need to update your Adapter connection, see Step 3: Select the Connection Type in the Integration Server Wrapper documentation.

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

  • CICS settings, for example TWASIZE. See CICS Settings in section Customizing the RPC Server under z/OS | z/VSE.

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

For a quick validation of your extraction, you can

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

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