Version 9.5 SP1
 —  Software AG IDL Extractor for COBOL  —

COBOL Parameter Selection

This document describes the COBOL Parameter Selection User Interface, its toolbars, context menus and panes. It also describes briefly the purpose of the COBOL Parameter Selection. It also provides background information on parameter selection. It contains the following sections:


COBOL Parameter Selection Purpose

The purpose of the COBOL parameter selection page is to select the COBOL data items that match the COBOL server interface. This allows you to perform the following tasks:

This page is used in Step 5: Select the COBOL Parameters of Scenario I: Create New IDL and SVM.

Top of page

COBOL Parameter Selection User Interface

The following page is provided for selecting the COBOL data items as parameters of your COBOL server:

graphics/parmSelection_interface.png

The page consists of the following main panes:

COBOL Data Items

In the COBOL Data Items pane, all COBOL data items contained in the LINKAGE and WORKING-STORAGE SECTION are offered in a tree view. Redefine units (all redefine paths addressing the same storage location) are marked with special icons (graphics/icon_redefineUnits.png). By default, the LINKAGE SECTION is expanded and the WORKING-STORAGE SECTION is not.

Context Menu

A context menu is available on the node items of the COBOL Data Items tree for selecting parameters. See toolbar description below for explanation.

Toolbar

The toolbar in the COBOL Data Items pane provides the following actions:

Action Description

graphics/icon_select.png

Select one or more unselected items and move them to the right section. The same action is provided from the context menu and with a drag-and-drop operation.

graphics/icon_expand.png

Expand the full tree.

graphics/icon_collapse.png

Collapse the full tree.

COBOL INOUT Parameters

In the COBOL INOUT Parameters pane, the currently selected parameters are presented in a tree view, representing the interface of your COBOL program.

Context Menu

A context menu is available on the node items of the COBOL INOUT Parameters tree for deselecting parameters. See toolbar description below for explanation.

Toolbar

The toolbar in the COBOL INOUT Parameters pane provides the following actions:

Action Description Restrictions

graphics/icon_deselect.png

Deselect one or more items and remove them from the right section. The same action is provided from the context menu and by a drag-and-drop operation. Deselection is only allowed on the first level, except of interface type CICS, where items on the level following the DFHCOMMAREA level can be selected.

graphics/icon_previous.png

Change the parameter order: move the selected item up. Only for Interface types BATCH and IMS BMP.

graphics/icon_next.png

Change the parameter order: move the selected item down. Only for Interface types BATCH and IMS BMP.

graphics/icon_deselectClear.png

Deselect all items and clear the section.  

graphics/icon_restoreDefault.png

Restore the default selection. Only on the INOUT or IN parameter selection page.

graphics/icon_expand.png

Expand the full tree.  

graphics/icon_collapse.png

Collapse the full tree.  

OUT Same as IN Parameters

The OUT same as IN parameters check box is available for interface types CICS with DFHCOMMAREA Calling Convention and CICS with DFHCOMMAREA Large Buffer Interface, and allows you to extract from a COBOL server with the same COBOL data structures on input and output, or with different data structures on input and output (i.e. the output overlays the input). See DFHCOMMAREA examples 1, 2, 3 and the DFHCOMMAREA Example 2 for CICS COBOL server with different data structures on input and output.

Find in Source

With the Find in Source feature you can search in the COBOL source and locate text. This is useful if there is a large linking or working storage section and if you know the name of the COBOL data item you are looking for at least in parts.

COBOL Source

The COBOL source pane in the lower part of the page is headed by a list of (selectable) tabs. If Source is selected, the source code you extracted is displayed. Additional tabs are related to the copybooks, CA Librarian (-INC control statement) or CA Panvalet (++INCLUDE control statement) members that are referenced in your sources. This way, you can easily switch between the source, the copybooks and members.

Notes:

  1. There are no additional tabs if there are no references to copybooks, CA Librarian (-INC control statement) or CA Panvalet (++INCLUDE control statement) members.
  2. Each single-parameter selection done in the COBOL Data Items pane is highlighted in the corresponding source or copybook. This makes it easier to monitor the interface composition.

It is possible to resize the page and also to change the size of all these panes within the lines between the sections to handle large COBOL sources. Selections in the tree will reflect selections in the opposite tree and always in the COBOL source where you find all references to the selected parameter.

Top of page

How to Select COBOL Parameters

Selecting the COBOL parameters differs depending on the interface type:

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

CICS DFHCOMMAREA

Depending on the programming style used in the CICS program and the various different techniques for accessing the CICS DFHCOMMAREA interface, finding the relevant COBOL data structures can be a complex and time-consuming task that may require CICS COBOL programming knowledge. Please note also the following:

Start of instruction setTo extract from a CICS DFHCOMMAREA program

  1. Clarify whether the OUT and IN parameters of your COBOL servers are the same or different. Different OUT and IN parameters mean that parameter formats (usage clauses) for the input differ from those of the output. The following picture illustrates this:

    graphics/parmSelection_how_dfh.png

    There are various possibilities for programming/coding such a COBOL server with different OUT and IN parameters, for example:

    If your COBOL server has the

  2. Select the INOUT parameters (of your COBOL server) by using the context menu or toolbars available in COBOL Data Items and COBOL INOUT Parameters. Even if the data structure remains the same for input and output, the techniques explained for the DFHCOMMAREA examples 1, 2, 3 above and others can be used to address an in-out structure. See the notes below.

  3. Choose Finish and continue with Step 6: Map the COBOL Interface to IDL with the Mapping Editor.

  4. Select the IN parameters in correct sequence and number by using the context menu or toolbars available in COBOL Data Items and COBOL IN Parameter. Consider the techniques explained for the DFHCOMMAREA examples 1, 2, 3 above and others to address the input structure. See also the notes below.

  5. Choose Next.

  6. Select the OUT parameters of your COBOL server by using the context menu and toolbars available in the COBOL Data Items and COBOL OUT Parameter pane. Consider the techniques explained for the DFHCOMMAREA examples 1, 2, 3 above to address the output structure. See also the notes below.

  7. Choose Finish and continue with Step 6: Map the COBOL Interface to IDL with the Mapping Editor.

Notes

CICS Channel Container

Modern CICS program may use the CICS channels and containers model. During extraction, containers are mapped to IDL structures. See structure-parameter-definition (IDL).

The page for selecting the COBOL data items that describe the container layouts contains a table on the right that provides an overview of the selected containers and their names.

graphics/parmSelection_how_channel.png

Start of instruction setTo extract from a CICS Channel Container program

  1. Define the CICS Input Container by selecting the Source tab and entering "EXEC CICS" in Find in Source to look for a GET call containing "EXEC CICS GET", function "CONTAINER" and the "CHANNEL", example:

    EXEC CICS GET
          CONTAINER(<container name constant>)
          CHANNEL  (<channel>)
          INTO     (<container>)
          NOHANDLE
    END-EXEC
    

    See Find in Source.

    Select the corresponding <container> in COBOL Data Items. Enter the container name, found in the value of <container name constant>. You can select multiple CICS input containers.

  2. Choose Next.

  3. Define the CICS Output Container using the steps as above, but look for "EXEC CICS PUT". Example:

    EXEC CICS PUT
          CONTAINER(<container name constant>)
          CHANNEL  (<channel>)
          FROM     (<container>)
          FLENGTH  (LENGTH OF <container>)
          NOHANDLE
    END-EXEC
    

    Select the corresponding <container> in COBOL Data Items. Enter the container name, found in the value of <container name constant>. The EXEC CICS PUT statement can be executed multiple times (for example in a loop) for the same container definition, creating an array of container. If this is true, set the column Array in the wizard to "Yes" and enter the maximum number of occurrences for the container in the Max column.

  4. Choose Finish and continue with Step 6: Map the COBOL Interface to IDL with the Mapping Editor.

Notes:

  1. The container name length is restricted to 16 characters.
  2. Arrays (direction OUT) will enlarge the container name, because the number of occurrence will be added to the name (max. 16 characters), for example MYCONTAINER00001.

CICS DFHCOMMAREA Large Buffer

A DFHCOMMAREA Large Buffer Interface has the structure given below in the linkage section. The field subordinated under DFHCOMMAREA prefixed with WM-LCB describe this structure. The field names themselves can be different, but the COBOL data types (usage clauses) must match exactly.

Large Buffer Example 1

 LINKAGE SECTION.
                                             
 01 DFHCOMMAREA.
    10 WM-LCB-MARKER                         PIC X(4).
    10 WM-LCB-INPUT-BUFFER                   POINTER.
    10 WM-LCB-INPUT-BUFFER-SIZE              PIC S9(8) BINARY.
    10 WM-LCB-OUTPUT-BUFFER                  POINTER.
    10 WM-LCB-OUTPUT-BUFFER-SIZE             PIC S9(8) BINARY.
    10 WM-LCB-FLAGS                          PIC X(1).
       88 WM-LCB-FREE-OUTPUT-BUFFER     VALUE 'F'.
    10 WM-LCB-RESERVED                       PIC X(3).
 01 INOUT-BUFFER.
    02 OPERATION                             PIC X(1).
    02 OPERAND-1                             PIC S9(9) BINARY.
    02 OPERAND-2                             PIC S9(9) BINARY.
    02 FUNCTION-RESULT                       PIC S9(9) BINARY.
  . . .
 PROCEDURE DIVISION USING DFHCOMMAREA.
  . . . 
    SET ADDRESS OF INOUT-BUFFER TO WM-LCB-INPUT-BUFFER.
    SET ADDRESS OF INOUT-BUFFER TO WM-LCB-OUTPUT-BUFFER.
*  process the INOUT-BUFFER and provide result
    EXEC CICS RETURN.

Start of instruction setTo extract from a CICS DFHCOMMAREA Large Buffer program

  1. Clarify whether the OUT and IN parameters of your COBOL server are the same or different. Different OUT and IN parameters mean that parameter formats (usage clauses) for the input differ from those of the output. The following picture illustrates this:

    graphics/parmSelection_how_large.png

    There are various possibilities for programming/coding such a COBOL server with different OUT and IN parameters. Example 2 below illustrates one of the possibilities:

    Large Buffer Example 2

     LINKAGE SECTION.
     01 DFHCOMMAREA.
       10 WM-LCB-MARKER                    PIC X(4).
       10 WM-LCB-INPUT-BUFFER              POINTER.
       10 WM-LCB-INPUT-BUFFER-SIZE         PIC S9(8) BINARY.
       10 WM-LCB-OUTPUT-BUFFER             POINTER.
       10 WM-LCB-OUTPUT-BUFFER-SIZE        PIC S9(8) BINARY.
       10 WM-LCB-FLAGS                     PIC X(1).
          88 WM-LCB-FREE-OUTPUT-BUFFER  VALUE 'F'.
       10 WM-LCB-RESERVED                  PIC X(3).
     01 IN-BUFFER.
        02 OPERATION                       PIC X(1).
        02 OPERAND-1                       PIC S9(9) BINARY.
        02 OPERAND-2                       PIC S9(9) BINARY.
     01 OUT-BUFFER.
        02 FUNCTION-RESULT                 PIC S9(9) BINARY.
      . . .
     PROCEDURE DIVISION USING DFHCOMMAREA.
      . . . 
        SET ADDRESS OF IN-BUFFER  TO WM-LCB-INPUT-BUFFER.
        SET ADDRESS OF OUT-BUFFER TO WM-LCB-OUTPUT-BUFFER.
    * process the IN-BUFFER and provide result in OUT-BUFFER
        EXEC CICS RETURN.

    If your COBOL server has

  2. Select the INOUT parameters (of your COBOL server) by using the context menu or toolbars available in the COBOL Data Items and COBOL INOUT Parameters pane. To do this, locate in the PROCEDURE DIVISION the SET ADDRESS OF <x> TO <y> statements, where <y> is WM-LCB-INPUT-BUFFER and WM-LCB-OUTPUT-BUFFER. Both statements should point to the same <x> as in the example above. The COBOL data item <x> - INOUT-BUFFER in our example - is the INOUT parameter you are looking for. Consider the notes below.

  3. Choose Finish and continue with Step 6: Map the COBOL Interface to IDL with the Mapping Editor.

  4. Select the IN parameters (of your COBOL server) by using the context menu or toolbars available in COBOL Data Items and COBOL IN Parameter. To do this, locate in the PROCEDURE DIVISION the SET ADDRESS OF <x> TO <y> statement, where <y> is WM-LCB-INPUT-BUFFER. The COBOL data item <x> is the IN parameter you are looking for. Consider the notes below.

  5. Choose Next.

  6. Select the OUT parameters (of your COBOL server) by using the context menu and toolbars available in the COBOL Data Items and COBOL OUT Parameter pane. To do this, locate in the PROCEDURE DIVISION the SET ADDRESS OF <x> TO <y> statement, where <y> is WM-LCB-OUTPUT-BUFFER. The COBOL data item <x> is the OUT parameter you are looking for. Consider the notes below.

  7. Choose Finish and continue with Step 6: Map the COBOL Interface to IDL with the Mapping Editor.

Notes

Standard Linkage

Because COBOL servers with standard linkage always contain a PROCEDURE DIVISION header (see PROCEDURE DIVISION Mapping) with all parameters, the COBOL parameters can be evaluated by the IDL Extractor for COBOL and are already offered by the wizard. In most cases the offered COBOL parameters will be correct, but you should always check them manually.

Start of instruction setTo extract from a Standard Linkage program

  1. Select the INOUT parameters (of your COBOL server) by using the Context Menu or Toolbar available in the COBOL Data Items and COBOL INOUT Parameters pane.

    Consider the following:

  2. Choose Finish and continue with Step 6: Map the COBOL Interface to IDL with the Mapping Editor.

IMS MPP Message Interface (IMS Connect)

Depending on the programming style used in the IMS processing program (MPP) and the various techniques for accessing the IMS input and output messages, finding the relevant COBOL data structures can be a complex and time-consuming task that may require IMS programming knowledge.

IMS Message Processing Programs (MPPs) work as follows:

Start of instruction setTo extract from an IMS MPP message interface (IMS Connect) program

  1. In Find in Source, enter "CBLTDLI" to look for an IMS system call containing 'CBLTDLI', function GU and the IOPCB pointer, example:

    CALL 'CBLTDLI' USING GU IOPCB <input-message>

    See Find in Source.

    Select the corresponding <input-message> in COBOL Data Items. See also IMS MPP Message Interface (IMS Connect).

  2. In COBOL Data Items, select the IN parameters (of your COBOL server) by using the Context Menu or Toolbar available. They are contained in fields after the technical fields LL (length of message), ZZ and the COBOL data item containing the transaction code which is mostly the third physical field starting from offset 5 (bytes) in the input message. Do not select the fields LL, ZZ and the transaction code. See the notes below.

  3. Choose Next.

  4. Similar to step 1, enter "CBLTDLI" in Find in Source to look for an IMS system call containing "CBLTDLI", function ISRT and the IOPCB pointer, example:

    CALL 'CBLTDLI' USING  ISRT IOPCB  <output-message>

    Select the corresponding <output-message> in COBOL Data Items.

  5. Select the OUT parameters of your COBOL server by using the Context Menu and Toolbar available in the COBOL Data Items and COBOL OUT Parameter pane. These are the fields after the technical fields LL (length of message) and ZZ. Also do not select LL and ZZ here.

  6. Choose Finish and continue with Step 6: Map the COBOL Interface to IDL with the Mapping Editor.

Notes:

IMS BMP Standard Linkage

If your IMS BMP program contains PCB pointers, you have assigned the IMS PSB list in the previous step Step 4: Define the Extraction Settings and Start Extraction. If a required IMS PSB list is not assigned, the PCB pointers are not detected; go back to Step 4: Define the Extraction Settings and Start Extraction and assign the IMS PSB list first.

If the IMS PSB list is correctly assigned, the COBOL parameters (including the PCB pointers) can be evaluated by the extractor because this type of COBOL server contains a PROCEDURE DIVISION header (see PROCEDURE DIVISION Mapping) with all parameters. In most cases the offered COBOL parameters will be correct, but you should always check them manually.

Start of instruction setTo extract from a IMS BMP Standard Linkage program

Top of page