Version 9.5 SP1
 —  Software AG IDL Extractor for COBOL  —

Scenario I: Create New IDL and SVM


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.

Top of page

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

or

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.

Top of page

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 COBOL Source from a Remote Host Computer (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 or 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 Partitioned Data Set (z/OS) or Selecting a Member from a CA Librarian Data Set (z/OS).

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

The following page offers all members contained in the partioned 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 (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 (z/OS)

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

graphics/createNew_selectSource_remote-zos_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 a COBOL Source from a Remote Computer

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

Selecting an Element (S) from an LMS Library (BS2000/OSD)

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.

Top of page

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

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

The Interface Type must match the type of your COBOL server program. It is used by the RPC server at runtime to correctly call the COBOL server. Selection of an unsupported interface type is likely to result in problems during execution. To select an appropriate interface type, see:

Depending on the interface type, additional information can be set. For the interface type

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

With the COBOL-to-IDL Mapping target options you specify how COBOL data items are 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

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

Start of instruction setTo complete the extraction

  1. Enter the COBOL program ID.

  2. Choose OK to continue with Step 5: Select the COBOL Parameters.

Top of page

Step 5: Select the COBOL Parameters

In this page you select the COBOL data items that form the COBOL INOUT parameters of your COBOL server program. For a detailed description of the functionality, context menus, toolbars and main panes of this page, see COBOL Parameter Selection.

graphics/createNew_selectParms.png

Selecting the COBOL parameters differs depending on the interface type and is described under How to Select COBOL Parameters.

Interface Type Proceed with ...
CICS with DFHCOMMAREA calling convention CICS DFHCOMMAREA
CICS with channel container calling convention CICS Channel Container
CICS with DFHCOMMAREA large buffer interface CICS DFHCOMMAREA Large Buffer
Batch with standard linkage calling convention Standard Linkage
Micro Focus with standard linkage calling convention Standard Linkage
IMS MPP message interface (IMS Connect) IMS MPP Message Interface (IMS Connect)
IMS BMP with standard linkage calling convention IMS BMP Standard Linkage

Top of page

Step 6: Map the COBOL Interface to IDL with the Mapping Editor

With the Mapping Editor you map the COBOL server interface selected in Step 5: Select the COBOL Parameters to Software AG IDL. The outcome of the Mapping Editor is the IDL and an SVM file.

graphics/extractorMappingEditor.png

For more information on the COBOL mapping editor's user interface, its decision icons, mapping icons, context menus, toolbars and main panes, see Mapping Editor User Interface.

Before you start to define the mapping in the COBOL mapping editor, clarify whether your COBOL server implements multiple business functions controlled by an operation or function code field and you have to extract all the functions, or whether the COBOL server implements just a single function.

Mapping COBOL Functions to Multiple IDL Programs

Optional. COBOL level-88 data items can be mapped to operation using the Map to operation function from the context menu.

Start of instruction setTo map operations of the COBOL server to IDL programs

  1. Call the context menu of the COBOL level-88 data item of the operation or function code field you want to map to an IDL program.

  2. Use the Map to Operation function for this purpose. The following rules apply:

Perform all the other mappings for the COBOL function described under Mapping a COBOL Interface to an IDL Program.

Mapping a COBOL Interface to an IDL Program

The following actions are required in the Mapping Editor if your COBOL server met the conditions:

The following mapping editor actions are optional. They remove uneeded COBOL parameters during the mapping process, which simplifies the extracted IDL. See the following sections:

Providing IDL Directions (IN OUT INOUT)

A very important task in the mapping editor is to choose the correct IDL directions (see direction-attribute in attribute-list under Software AG IDL Grammar) of the COBOL parameters, because in COBOL programs there is no parameter direction. You have to do this in the mapping editor because it is not possible to do this after extraction by simply editing the IDL file extracted - the related SVM file would no longer match the IDL. For CICS servers that overlay the IN parameters with different OUT parameters, it is not possible to provide IDL directions manually - there is only one IDL direction offered. It is also not necessary, because the correct IDL directions are already implicit in step Step 5: Select the COBOL Parameters.

Start of instruction setTo provide IDL directions

Please note the following:

Selecting REDEFINE Paths

If your COBOL server contains COBOLREDEFINES, a required and very important task in the mapping editor is to choose the correct REDEFINE paths of a COBOL REDEFINE data item for your mapping.

Start of instruction setTo select redefine paths

  1. Use the Map to IN, OUT or INOUT functions of the Context Menu for this purpose. The following rules apply:

  2. Select the correct redefine paths beginning with a COBOL REDEFINE defined at the top-level first. For a CICS COBOL server, the top-level COBOL data items are the COBOL data items directly under DFHCOMMAREA. For all other COBOL servers, the top-level COBOL data items are defined with COBOL level 1.

  3. Work through all inner COBOL REDEFINE data items, going from higher levels to lower levels.

  4. We recommend using the Up and Down buttons of the Toolbar to locate the COBOL REDEFINE data items in the right order.

Suppressing or Hiding Unneeded Fields of the COBOL Server

Optional. With the mapping editor you can make COBOL data items of the COBOL server interface invisible for IDL clients. This means the fields are not mapped to IDL, which makes sense for COBOL data items that do not have any meaning, for example FILLER.

Start of instruction setTo suppress or hide unneeded fields

Mapping COBOL Data Items to Constants

Optional. With the mapping editor you can provide fixed values to COBOL data items of the COBOL server at runtime. In this case, the COBOL data items are also invisible for IDL clients, which means the fields are not mapped to IDL. This feature keeps the IDL short and tidy: IDL clients are not bothered by fields that always contain constants, such as RECORD-TYPES.

Start of instruction setTo map COBOL data items to constants

Top of page

Step 7: Finishing the Mapping Editor

When you choose Save in the Mapping Editor, the IDL and SVM files are generated. Both files are written with the "File Name" entered for the IDL file in the IDL Extractor for COBOL wizard. See Step 4: Define the Extraction Settings and Start Extraction. The extension used for the IDL file is *.idl and *.svm for the SVM file.

The following dialog is displayed whenever the Mapping Editor is saved. There are two options to choose from:

graphics/saveMappingEditor.png

Start of instruction setTo save the generated files into the workspace, quit the Mapping Editor and deploy the SVM file

  1. Select Save Software AG IDL and SVM files.

  2. Check the option Deploy SVM and choose OK. Continue with Step 8: Deploy the SVM File (Optional).

Start of instruction setTo save the generated files into the workspace and quit the Mapping Editor without deploying the SVM file

  1. Select Save Software AG IDL and SVM files.

  2. Clear the option Deploy SVM and choose OK.

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 SVM file will be lost, resulting in unexpected behavior.
Warning:
An SVM 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 existing COBOL server.

Top of page

Step 8: Deploy the SVM File (Optional)

If an SVM file is required, it has to be provided. For RPC servers this is done by deployment, either by using a wizard or by a manual approach specific to the RPC server used, see Server Mapping Deployment. For the webMethods 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.

Top of page

Step 9: 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.

For a quick validation of your extraction, you can

Top of page