Advanced copybook selection

This section describes the method for specifying an advanced copybook source definition. To navigate to the panels mentioned, see Advanced copybook source definitions.

  1. The Library List panel is displayed as the initial panel when creating a new template. You can display this panel with the LIBLIST command from the Copybook Selection panel.

    You can specify up to 12 data set libraries. The data sets may be PDSs, PDSEs, CA-Panvalet libraries, or other library management system libraries. You can specify multiple PDSs, PDSEs, CA-Panvalet and other library management system libraries but they must be either all PDSs or PDSEs, or all CA-Panvalet, or all the same library management system libraries. You cannot mix library types.

  2. Press the Exit function key (F3). The Copybook Selection panel is displayed initially for new templates where the member has not been supplied (after the Library List panel), for new templates where a generic member name was specified on the Copybook section, or when the U prefix command was specified with a template data set name and member name to update the source definition for an existing template.
  3. Type an ā€œSā€ in the Sel field for each member that you want to select.

    You can browse (B), edit (E), or view (V) each of the members on this list before selecting the ones you want.

    Note:
    1. All members must contain copybook definitions in the same language.
    2. If you specify a member that consists of an entire program, then you should use the X prefix command to specify a statement range to extract the field definitions you are interested in, otherwise you may get compile errors when mixing with other members.
    3. You can only edit members in a PDS or PDSE data set.
    4. Library members may not be packed by ISPF.
  4. When you have selected all of the members you want, press the Exit function key (F3). The selected members are listed in the Copybook Selection panel.

    From the Copybook Selection panel, you can display (and modify if necessary) the current library list by entering the LIBLIST primary command.

  5. Edit the list of members to suit your requirements. You can copy or move members, insert or delete members and create new 01-level fields for any member. You can also specify redefines or range values for a member.

    To add a new member:

    1. Enter the I prefix command to insert a new row.
    2. Type an asterisk or member name pattern in the Member field, then press Enter
    3. Select the new member name or names from the list. The list is not affected by any pattern that you have entered on the Template Workbench, it is a new list of all members in all selected databases, filtered by the pattern entered on the Copybook Selection panel.
    4. Press the Exit function key (F3). The selected members are inserted into your list on the Copybook Selection panel.

    To create a new 01-level field for a member:

    1. On the Copybook Selection panel, type a Y in the 01 field adjacent to the member.
    2. In the adjacent Field Name field, type a name for your 01-level element. This name must follow the naming conventions for the language of the copybook. If the name is omitted, Z Data Tools generates a random name when the template is compiled.

    To extract a subset of the copybook to be compiled into the template:

    1. From the Copybook Selection panel, type an X in the Cmd field next to the required copybook member to display the Redefines / Range Specifications pop-up panel.
    2. In the From statement field, specify the starting line number for the extract.
    3. In the To statement field, specify the ending line number for the extract.
    4. In the From string field, specify the string that Z Data Tools is to search the copybook for. The first statement that contains the string begins the extract.
    5. In the To string field, specify the string that Z Data Tools is to search the copybook for. The first statement that contains the string ends the extract.

    See the panel definition for a complete list of the prefix commands available.

  6. To generate multiple record layouts for a source that contains more than one record definition within a single level-01 structure:
    1. From the Copybook Selection panel, type an X in the Cmd field next to the required copybook member to display the Redefines / Range Specifications pop-up panel.
    2. In the Level field, specify the source level value to identify the COBOL REDEFINES or the PL/I UNION clauses for generating new record layouts. Z Data Tools creates a separate record layout for each REDEFINES or UNION clause at the specified level. After the first matching REDEFINES or UNION clause is found, Z Data Tools creates new layouts for the latter and subsequent REDEFINES or UNION clauses for the same level and start location. Header and trailing data items are included in each record layout.
      Note: This field is ignored for HLASM compiles.
    3. In the Field name field, specify the target field name of the COBOL REDEFINES, PL/I UNION, or HLASM ORG clause, that identifies the COBOL REDEFINES, PL/I UNION, and HLASM ORG statements that are to be used to direct Z Data Tools to create new layouts.

      This is an alternative way of identifying COBOL REDEFINES, PL/I UNION, and HLASM ORG statements that require new layouts to be generated. You can specify both Level and Field name values; Z Data Tools checks both when generating new layouts.

    4. To adjust the offset value for each layout so that the starting location is the REDEFINES, UNION, or ORGfield start location, enter a "/" in the Set offset field.

      Use this option when your record layouts do not include the header data items in the structure. You can only select this option in conjunction with the previous fields.

    5. COBOL level change: This is a COBOL ONLY option which changes the way the Level value is processed. If you set this option, every occurrence of the specified Level value is changed to '01" before the compile step, irrespective of whether the data item has a REDEFINES clause.

      Use this option with care as it may result in incorrect offsets to data items, or compile errors, due to the structure being changed from its intended programmable form.

  7. To compile the specified copybooks from the Copybook Selection panel, and either update an existing template or create a new template, use the UPDATE primary command or the U prefix command.
  8. To edit an existing template built from the copybooks specified on the Copybook Selection panel, use the EDIT primary command or the E prefix command. If you have made any changes, Z Data Tools compiles the copybooks and updates the template.
  9. When your Copybook Selection list is completed, press the Exit function key (F3).

    The compiler attempts to create the template for you.

    If the compilation is unsuccessful, the Template Not Built pop-up panel is displayed, offering you the following choices:

    1. View the compilation listing.
    If you select this option, the compilation listing is displayed so that you can determine the cause of the error. When you have finished viewing the listing, press the Exit function key (F3) to return to the Copybook Selection panel, correct the problem, then try to exit the panel again.
    2. Abort processing.
    Returns you to the Copybook Selection panel, where you can correct the problem, then try to exit the panel again.
    3. Retry (recompile copybook)
    Attempts to submit the same details again. If the compilation had failed because a member was temporarily unavailable, this may resolve the problem.
    4. Retry (with alternate compiler)
    Attempts to submit the same details again but with the alternative compiler. If the compilation had failed because the Z Data Tools default compiler was set to the wrong compiler for this copybook language, this may resolve the problem.
    Note: This choice does not apply to HLASM.

    If the compilation is successful, you are prompted to save it to the template member specified on the Template Workbench panel. If you had supplied a member name pattern or left the Template: Member field blank on that panel, the Template Member Selection panel is displayed. You can select a name from this list and press Enter to overwrite the existing selected member, or you can press the Exit function key (F3) and you are prompted to name a new member.

Related topics