Tutorial 3: Convert MVS QSAM File to Flat File

This tutorial assumes that users have installed File-AID/EX Enterprise Edition on a Mainframe. Refer to the chapter on installing the File-AID/EX Enterprise Edition in the File-AID/EX Installation Guide for installation instructions.

Important

OPTION 4 - TRAINING OPTIONS must be installed during File-AID/EX Enterprise Edition Installation before users can complete this tutorial.

In this tutorial, users will learn how to convert an MVS QSAM hierarchical dataset to a  flat file. This tutorial also teaches how to change packed fields to string data types, using the Record Layout Editor.

Conversion Type: One-to-One.

After completing this tutorial, users will be able to do the following:

  • Define data source and data target connections.
  • Import a COBOL copybook.
  • Map a source to a target using automapping.
  • Edit the record layout using the Record Layout Editor.
  • Save and run the conversion specification.
  • Browse source and target data.

Source and Target Data Descriptions

Data Source

Connector Type: QSAM

Dataset Name: <user ID>.FESAMP.PARTS.SEQ

where <user ID> is the high level qualifier that the installer used to copy the dataset. Refer to “Copy the Dataset from the Media”.

Data Target

Connector Type: Flat File (Flat File will be changed to Delimited File using the Record Layout Editor)

File Name: parts.asc

File location: c: or the user’s directory path

About the Dataset

The dataset for this conversion is located on the media shipped with the product. It includes engineering parts file information. This tutorial writes the dataset to a flat file.

Copy the Dataset from the Media

The dataset for this tutorial is provided in the Training Files installed with File-AID/EX Enterprise Edition. If the administrator installed all of the options during Enterprise Edition Installation, then it is only necessary to run the CLIST to make a copy of the datasets for individual use. The CLIST copies the base training file under the High-Level Qualifier that the user provides.

While running the CLIST, the following error may be encountered:

MASTER TRAINING FILES NOT FOUND
CONTACT YOUR FILE-AID/EX ENTERPRISE INSTALLER

This means the Training Files were not installed with the File-AID/EX Enterprise Edition installation. Have the administrator select and install OPTION 4 - TRAINING OPTIONS during File-AID/EX Enterprise Edition Installation. For more information, refer to the File-AID/EX Installation Guide.

Define the Data Source

After starting ConverterPro, begin defining source data and connection information using the Data Sources tab.

  1. In  ConverterPro,  click  New (image2021-8-27_14-58-46.png).
  2. From the Connector Type list, select QSAM to establish a QSAM source connection. The QSAM pane appears.
  3. In the Connector Name field, type QSAM_PARTS.
  4. Obtain the host TCP/IP address and port number from the MVS systems administrator. Type this information in the Host TCP/IP Address and Port Number fields. Valid port numbers include 1 through 65,535.

  5. In Dataset Name, type your user ID, followed by a period, and FESAMP.PARTS.SEQ. 

    For example: yourID.FESAMP.PARTS.SEQ

    This is the data source for this conversion specification.

  6. In the User ID and Password fields, type your mainframe user ID and password.
  7. Click Next. Since there are no existing record layouts in this conversion, the Record Layout Selection pane appears so users can create or import table or file layouts.
  8. Import record layouts by selecting a record layout type from  the  Record  Layouts Type list. In this case, COBOL - OS/390 Copybook is selected. Keep this selection.

  9. Type the layout dataset name and member name for PDS datasets in the field. For example:

      YOURID.FESAMP.LAYOUTS(PARTS)
  10. Click Next. The record layout table pane appears showing field names, data type, encoding type, record number of occurrences or field length, and comment text if available for the record or field. This may take a few minutes. The record layout is complete.

  11. Click Next to finish defining the QSAM (source) connection. The first pane of the Data Targets tab appears.

    Important

    The Project Tree view is updated to display the PROD001_PART_TABLE file and QSAM_PARTS connector. The dataset name is displayed below the PROD001_PART_TABLE file. Click the file name, dataset name, or connector to display the respective properties in the Properties view. Refer to the ConverterPro online help for detailed project tree and properties information.

Define the Data Target

Define target connection and data using the Data Targets tab.

  1. From the Connector Type list, select Flat File to establish a flat file target connection. The Flat File panel appears.
  2. In the Connector Name field, type PARTS_FLATFILE.

  3. In the File Name field, type c:\parts.asc or <your directory path>\parts.asc.

    Important

    Ensure that the directory path specified is a valid and locally mapped drive and path.

    The parts.asc file is the data target in this conversion specification.

  4. In the Target Action (Exist/Not Exist) list select Recreate/Create.

  5. Click Next. The Record Layout Selection pane appears. The Existing Record Layouts column shows the previously imported source record layout (PROD001_PART_TABLE).

    Since a flat file is selected as the data target, a record layout that describes the fields in this file must be specified. In this conversion specification, the output record layout file must be an exact copy of the input record layout file.

  6. Select PROD001_PART_TABLE and click Add (   ) to add the file to the Selected Record Layouts column.
  7. Click Next. The record layout table appears. It looks exactly like the source record layout. Do not change anything on this pane.
  8. Click Next. The Mapping Editor grid appears. The project tree view is updated to display the PROD001_PART_TABLE data target and PARTS_FLATFILE connector. The path and file name are displayed below the data target.

Map the Source to the Target

Use the Mapping Editor grid to specify source to target mapping.

Fields from the PROD001_PART_TABLE (source) appear on the left in the grid. Fields from the PROD001_PART_TABLE (target) appear on the right.

Editing the Record Layouts

Change the RecordDelimiter property to designate a record delimiter and change packed data types to string data types:

  1. In the project tree view, right-click the PROD001_PART_TABLE data target and select View\Edit Record Layout. The Record Layout Editor window appears.

  2. Click the RecordDelimiter property value and select CR-LF (carriage return-line feed) from the list. A carriage return-line feed is placed at the end of each record after the record is written. This property is displayed only when the record is selected (the top line), not when a field is selected.

    Important

    Whether the packed data types need to be changed to string data types  depends on how the target file created will be used. To create a target file that will be uploaded back to the mainframe, leave the  packed fields unchanged. To  use this file on Windows or  UNIX, change them to string. For this  tutorial, they will be changed to string.

  3. In the Type column, click the list for the first Packed field and select String. Select each of the other packed fields and change them to String also.
  4. Click OK to save the information and return to the ConverterPro window.

Using Automap

Use the automapping feature to map each field in the source to a corresponding field  in the target. When no clear correlation exists between the source and target, a source field must be manually dragged and dropped onto a target field. In this tutorial, source fields are identical to the target fields, so automapping can be used.

  1. From the Source column, right-click on PROD001_PART_TABLE and select Automap > By Field Name Match. All like-named fields are mapped. In this case, all fields are mapped since the source and target field names are identical.  The  results appear in the Mapped Field column.
  2. Click Next. The Conversion Customization pane appears. Do not change anything on this pane.
  3. Click Next. The Conversion Execution pane appears.

Save and Run the Conversion Specification

Before running this conversion specification, save it to the repository.

  1. From the File menu, select Save. The Save Conversion As dialog box appears.
  2. In the Name field, type Tutorial3.

  3. In the Description field, type QSAM to flat file.

    The Save with Userid/Password option is selected. Keep this selection.

  4. Click OK to save the specification.
  5. In Data Targets, on the final Mapping Editor pane, verify that Recreate/Create is selected in the Target Action list.

  6. From the Actions menu, select Run. The Execution Summary Viewer appears showing the progress of the conversion. This may take a few minutes to execute since it is accessing information from the mainframe.

    The Execution Summary Viewer Summary tab shows the conversion specification name (Tutorial3), execution submission date, and time. It also shows that 56 records were read from PROD001_PART_TABLE (source) and written to PROD001_PART_TABLE (target). It also shows that no records were discarded.

    The Execution Summary Viewer has two tabs: Summary and Detail. Click the Details tab to see additional information about the conversion specification. The parts file is written to the directory path specified.

  7. When the status message says Complete, click Close.

Browse the Source and Target

To verify what was written to the target, compare the data in the Source Data Browser

with the data in the Target Data Browser.

  1. From the Tools menu, select Browse Source. The Source Data Browser appears.
  2. From the Tools menu, select Browse Target. The Target Data Browser appears to show PROD001_PART_TABLE contents.
  3. To  confirm that  the  conversion copied the  file  correctly,  click image2021-8-27_15-21-39.pngto compare the results.
  4. After browsing the source data, click OK to return to the ConverterPro window.

Tutorial 3  is  now complete.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*