Requesting z/OS Datasets

The File-AID Data Editor Request dialog for z/OS datasets captures your options for accessing z/OS datasets. You can provide record layouts and specify selection criteria to limit the records and fields you wish to access. You can also establish other display and run options such as Browse mode or Edit mode.

You can save and re-use your request, making it easy to access your data the same way the next time you access this object. Your recently used requests are listed on the Data Editor menu accessed by clicking the toolbar File-AID icon image2021-3-11_17-55-12.pngand selecting Data Editor.

Creating a New or Using a Saved Request

To create a new or use a saved request:

  1. At the top of the File-AID Data Editor Request for z/OS datasets dialog, enter a Request Name to create a new request, or select a request name from the request name pull-down list to use an existing request. 

    Note

    If you try to create a request with a name that has already been used, a message will appear asking whether you want to overwrite the existing request. z/OS dataset request names created by a single user, or all users in a single workspace, must be unique even for different files. If you have requests for several files and have trouble remembering what request names you have already used, you could use naming conventions for your requests where requests for a specific file start with a specific letter or group of letters. For example, requests for files for the Human Resources department could start with HR and requests for the Sales department could start with SA. Then, request name HRTest would be different from SATest.

  2. You can optionally reassign the request to a different dataset. Either type the new dataset name in the Dataset field, click Browse to initiate the Dataset Selection dialog to navigate the catalog to find the desired dataset, or select a previously used dataset from the Dataset pull-down list. To save the request with the new dataset name, enter a new Request Name and click Save. 

    Note

    After the request has been run, the newly specified dataset will be available on the Dataset pull-down list.

    Using Record Layouts

    Record Layout Information

    Select whether to use record layouts. The Use record layouts checkbox initial state is controlled by a preference. The default is that it is selected and that you will be using Record Layouts to format your z/OS data. When Use record layouts is selected, by default the Single layout radio button is selected. If you wish to use a layout cross reference (XREF) definition to automate layout presentation for files with multiple record types or multiple segments of data per record (segmented records), click the Record layout cross reference (XREF) radio button and go to step 4.

    Note

    If Use record layouts is not selected, the Single layout and Record layout cross reference (XREF) radio buttons are disabled.

    Note

    XREF support requires that File-AID/MVS be updated with current maintenance. If the Record layout cross reference (XREF) radio button is disabled, it is likely that File-AID/MVS is not current.

    Single Record Layouts

  3. For a Single layout, enter the Layout dataset and member, then click the Get Layout button. Optionally you may use the pull-down control to list and select previously entered layouts, or click Browse to initiate the Dataset List dialog to navigate the catalog to find the dataset or member containing the layout you wish to use with this file.

    1. Click Browse. The Dataset Selection dialog box appears.
    2. Enter a partial name in the Datasets Name box. You can use the asterisk wildcard. Click List. A list of all datasets that meet the filter requirements appears.
    3. Select the desired layout dataset. If the dataset is a PDS, this populates the list of members for this dataset.
      To refine the list of datasets, use the Sequential icon (image2021-3-11_18-9-23.png) or PDS icon (image2021-3-11_18-9-48.png) (toggle buttons) to include only those types of datasets in the list. The default is for both to be selected when you first open the Dataset Selection dialog box. Clicking each icon the first time deselects that type of file.
      Clicking again, reselects that type of file. This updates the dataset list with only the selected type of dataset making it easier to search the list for the desired file.
    4. For a selected PDS, click on the desired member name from the member list. Optionally, use the Member Name box to specify a partial member name to reduce the size of the member list. The list is dynamically refreshed with each character you type.
    5. To verify that you have chosen the correct dataset and member, click View. This displays the file for viewing. Click Close to return to the Dataset Selection dialog box.
    6. After making your selection, click OK. You will return to the z/OS dataset Request window. To confirm that you have properly provided a layout, the Data Editor retrieves and compiles the layout and displays the metadata for the layout in the Fields tab of the selection criteria.
    7. If your layout has more than one 01 level name, select one from the list. Get Layout is only enabled if you entered the Layout dataset(member) manually. If you used Browse to make your selection, the layout is retrieved and compiled automatically.

    Record Layout Cross Reference (XREF)

  4. If you chose the Record layout cross reference (XREF) radio button, enter the XREF Dataset and member. Optionally you may use the pull-down control to select previously entered XREF dataset(member) names from the list, or click Browse to initiate the Dataset Selection dialog to navigate the catalog to find the dataset and member containing the XREF you wish to use with this file. You must also fill in the name of the Record layouts PDS. Optionally you may use the pull-down control to select previously entered Record layout PDS names from the list, or use the Browse button to locate the PDS containing the COBOL or PL/I layouts referenced in your XREF. 

    Note

    XREF datasets and members are created and maintained with the XREF utility of File-AID/MVS or the XREF editor in File-AID/Eclipse. For more information, see Creating a New or Editing an Existing XREF Member.

    Edit z/OS Dataset Selection Criteria

    Selection criteria determines what portion of the selected z/OS dataset becomes available for viewing or editing. You can choose which fields will be displayed and conditions for selecting records. Only records that match your selection criteria will appear in the editor data display.

    To edit z/OS dataset selection criteria

  5. Optionally, click on the Fields tab and select the desired fields. The search box near the top can be used to quickly find the desired fields. The fields you select are the only fields that will be viewable when you navigate to the Layout Formatted tab of the Data Editor. By default, all fields are automatically selected. 

    Note

    The Fields tab indicates "no layout information" and is empty when using an XREF. Field selection is not currently supported when using an XREF.

  6. Optionally, click on the Conditions tab. Records will be chosen based on the conditions selected. You can add conditions or sets. Sets can contain multiple conditions. If you prefer, you can optionally select Use selection criteria dataset(member). In this case, enter or search for the desired selection criteria dataset and member.

    Important

    Some Edit mode functions (Insert, Repeat, and Delete) are restricted for certain dataset types. VSAM ESDS non-reusable or not exclusive, VSAM ESDS or KSDS reusable exclusive when using selection criteria Conditions or Options. Note: Selection Criteria you use from the mainframe must be a valid selection criteria member in a File-AID/MVS Selection Criteria PDS.

  7. Under Field, click on <select field>.
    If you have provided a single record layout, the Choose Field Mode dialog box appears. From the Choose Field Mode dialog box, select Formatted or Unformatted fields when defining conditions for this set and click OK.
    1. If you selected Formatted, the Select filter field window appears. Click the field name to select the desired field and click OK. You can select only one field. You will return to the File-AID Data Editor Request window. 
    2. Select an Operator from the list (is equal to is the default). Operators are only available for selection after you have selected a field under Column Name. For more information, see z/OS Selection Criteria Operators.

    3. Type a value in the Value column. Not all operators require a value. For more information, see z/OS Values. 

      Note

       When entering a value for a Formatted Set condition, the value must match the format of the field layout. You must enter decimal numbers for numeric fields. If you need to specify values more explicitly, use the User Defined Field unformatted condition. There, you can specify your own data type including hex (X).

      If you selected Unformatted, or if you have not provided a record layout, or if you selected Record layout cross reference (XREF), the User Defined Field window appears.

    4. Enter a column Location where this user-defined field begins: A number from 1 to 32,767, as long as it is not larger than the maximum record length permitted for this file. If the specified location is beyond the end of a record, the condition is ignored and not used to select records.
      Location can also be specified as a relative number. +0 indicates the current location pointer (byte 1 initially). The location pointer is advanced when a prior condition uses the Contains operator and the data is located in the record. Relative locations can be negative as long as the sum of the relative location and the current location pointer is not 0 or less. If a location is zero or negative, the condition is ignored.
    5. Optionally, enter the field Length: Length is generally not required. The length of the Value you enter is used as a default. For the Contains operator, a length of 0 or blank implies “to the end of the record”. For Data Type B (Binary), you must specify a length of 1, 2, or 4. Length is ignored for data type M (Mask) as only one byte (2 hex digits) of value is allowed for this data type. For P (Packed) data types, length is automatically determined based on finding a valid packed field of any length at the specified location. If specified with data type P (Packed), the condition looks for a packed field of the length you provide.
    6. Select a Data Type: Choices include:
      • Any Case Text (T) (default): The values you enter are used to compare with the data at the specified location and will match any case (upper, lower, or mixed) of the entered strings.
      • Exact Case Text (C): The values you enter are used to compare with the data at the specified location and will match only the exact case of the entered strings.
      • Hex (X): The value is expected to be one or more even pairs of hex digits 0-9,A-F. The values you enter are used to compare with the data at the specified location and will match the hex values of the data in the record.
      • Packed (P): Typically the value you enter is a signed or unsigned decimal integer, it is used to compare with the data at the location in packed format. If the value you enter is unsigned or positive, it will match a positive or an unsigned packed number at the specified location. If negative, it will only match a negative packed number at the specified location.
      • Binary (B): Similar to Packed, the value you enter is a signed or unsigned decimal integer. A length (1, 2, or 4) is required with this data type. The value you enter is converted to a binary value and compared to the binary data at the specified location.
      • Numeric (N): Also similar to packed, the value you enter is a signed or unsigned decimal integer, it is used to look for zoned numeric data at the specified location (and for the specified length or the length of the value you enter). If the value you enter is unsigned or positive, it will match a positive or an unsigned zoned decimal number at the specified location. If negative, it will only match a negative zoned decimal number at the specified location. Signs are checked in the last digit of the field only. (Unsigned or positive numbers will match F zone or C zone numbers, and negative numbers will match D zone numbers. Example: Numeric -15 matches a data value of Hex F1D5.)
      • Bit Mask (M): This data type tests for individual bits in one byte of data at the specified location. The value specified is a pair of hex digits 0-9, A-F. Example: FF is a binary mask equivalent to 11111111. Special operators are provided when using this data type: is equal to (all ones, all 1s in the mask are on in the data), is not equal to (not ones, all 1s in the mask are off in the data), are mixed ones and zeros (some 1s, but not all, in the mask are on in the data), are not ones (not all 1s in the mask are on in the data). The operators are mixed ones and zeros and are not ones are only used when the bit mask contains more than one 1 and have no meaning if there is only 1 bit to test. When the mask has only one bit, the operator is equal to is the same as are mixed ones and zeros, and the operator is not equal to is the same as are not ones.
    7. Enter an Operator: Operators for user defined fields are the same as those provided for Formatted conditions. In addition, there are some special operators for the Bit Mask (M) data type as described in Data Types. Is equal to is the default. For more information, see z/OS Selection Criteria Operators.

    8. Enter the Value: Values are expected to be consistent with the Data Type you selected. Alphanumeric strings for Any Case Text (T) or Exact Case Text (C), decimal (0-9) signed or unsigned numeric values for Packed (P), Binary (B), and Numeric (N) data types. For Hex (X) you must enter one or more contiguous pairs of hex digits (0-9,A-F). 0000-FFFF. For more information, see z/OS Values.

      Notes

      For Bit Mask you must enter exactly two hex digits (0-9,A-F) or eight binary digits (0-1). Examples 0F or 00001111. You may specify multiple values separated by commas to create an OR test for this condition. For example, a,b,c means a or b or c. When using the special operators is a valid field and is an invalid field for numeric fields, do not specify a value. Instead, leave it blank.

    9. Click OK. You will return to the File-AID Data Editor Request window.

  8. To enter more than one condition, click When entering a value for a Formatted Set condition, the value must match the format of the field layout. You must enter decimal numbers for numeric fields. If you need to specify values more explicitly, use the User Defined Field unformatted condition. There, you can specify your own data type including hex (X). and repeat the previous step for each additional condition. 

    Notes

    • When multiple conditions are created (for z/OS) AND is always used to match how conditions are used on the mainframe.
    • To eliminate a condition, click on the condition to select it, then click the Remove button. To remove all conditions, click the Remove All button.
    • You may optionally click on the condition to select it, then click the Duplicate button to insert a copy of the condition following the current condition.

  9. To enter more than one set, click Add Set.

    Notes

    When multiple sets are created (for z/OS) OR is always used to match how sets are used on the mainframe. You cannot mix formatted conditions and unformatted conditions in one set.

    Options - Starting Point and More

  10. Optionally, click on the Options tab. Options allow you to set a starting point in your file by Key or RBA or by skipping a number of records. You can also set up a random selection interval and limit the number of records searched or selected before returning data. Finally, you can specify read backward for most file types. If you want to use any of the options, you must select the Yes radio button on the Activate these options prompt at the top of the Options tab. Activating options may limit edit functionality. Hover your mouse over the information icon at the beginning of the Activate prompt to view the restrictions.

    Query and Display Options

    Records to display per page

  11. Enter the Records to display per page. The default is 2000. This value determines page size for large files and allows rapid response to MVS data requests when the number is smaller. Maximum limit of page size varies based on the amount of free memory available to the File-AID Data Editor and the size of the records in the file.

    Notes

    The Records to display per page is set in the Windows > Preferences > Compuware > File-AID Data Editor preferences.

    I/O Exit

  12. Optionally, enter the name of a valid File-AID/MVS I/O exit. Your exit must exist in the File-AID/MVS authorized customization load library. I/O exits are used to allow user control for handling record data. Refer to the File-AID Single Install Image Installation and Configuration Guide for details on I/O exits. 

    Note

    Selection criteria Conditions and Options are not supported when using a Type 2 (full I/O control) I/O exit.

    Run Mode Settings

  13. Specify whether you want to view your data in Browse or Edit mode. Edit is the default. If you select Edit, specify whether to Enable Auditing. Enabled is the default. Also specify whether you want Exclusive use or shared use. Shared (unchecked) is the default. 

    Note

    The Records to display per page and Enable auditing default is set in the Windows > Preferences > Compuware > File-AID Data Editor (MVS tab) preferences.

    Note

    Maximum audit trail data area is 32724. If this size is exceeded, an error message will appear.

    Request Actions

  14. Once you have completed your request, it is a good practice to assign a Request Name and click Save to ensure that you can reuse the request in the future. Saved requests are accessible via the pull-down control in the Request Name field or via the Data Editor menu accessed by clicking the toolbar File-AID icon image2021-3-11_19-59-30.pngand selecting Data Editor.

  15. Click Run. You will navigate to the data display view.

    Note

    After you navigate to the data display, you can return to the Request by clicking the Return to Request link. There you may choose to update your criteria selections. Then optionally click Save to save your updates, and click Run again. Your data display view will be updated immediately with the new selection criteria.

  16. Click Close to exit the Request dialog.
  17. To delete a saved request permanently, click Delete.
  18. To return to the last saved state of a request, use the Revert button.

z/OS Selection Criteria Operators

Following is a description of the operators available for selection criteria conditions.
For information on how to edit your selection criteria, see Edit z/OS Dataset Selection Criteria.
When defining a formatted selection criteria condition, the format of the field is used to control the available operators and the valid values for entry.

Note

Comparisons are based on the EBCDIC collating sequence.

  • is equal to: will select all records that contain the specified value in this field.
  • is not equal to: will select all records that do not contain the specified value in this field.
  • is greater than: will select all records with contents that appear alphabetically after the specified value in this field. The specified value is not selected.
  • is less than: will select all records with contents that appear alphabetically before the specified value in this field. The specified value is not selected.
  • is greater than or equal to: will select all records with contents that include the specified value and appear alphabetically after the specified value in this field.
  • is less than or equal to: will select all records with contents that include the specified value and appear alphabetically before the specified value in this field.
  • is between: You must use the colon (:) separator with two values. For example, 5:10 or ABLE:CAIN will select all records that contain data equal to or greater than the first value (before the colon) and less than or equal to the second value (after the colon) in this field.
  • is not between: You must use the colon separator with two values. For example, 5:10 or ABLE:CAIN will select all records that contain data less than the first value (before the colon) and greater than the second value (after the colon) in this field.
  • contains: will select all records that contains the specified value anywhere within this field (only available for character fields).
  • does not contain: will select all records not containing the specified value anywhere within this field (only available for character fields).
  • is a valid field: will select all records containing valid data in this field. No value is needed or used with this operator, and it is only available for numeric packed and numeric decimal fields.
  • is not a valid field: will select all records containing invalid data in this field. No value is needed or used with this operator, and it is only available for numeric packed and numeric decimal fields.

z/OS Values

When entering values on the z/OS criteria selection window, the following rules apply.

When defining formatted conditions, you may enter a value consistent with the selected field format: numbers for numeric fields and alphanumeric for character fields. You may specify multiple values separated by commas to create an OR test for this condition. For example, a,b,c means a or b or c. Alphanumeric data is case sensitive. To define case insensitive conditions you must use unformatted sets and conditions.

When using the special operators is a valid field and is an invalid field for numeric fields, do not specify a value. Leave it blank.
If the field is a FIXPIC or FIXDEC numeric format, your value must not exceed the size of the picture clause. For example, when using PIC S9(2)V9(3), you may enter no more than two digits to the left of the decimal point and no more than three digits to the right of the decimal point. The picture clause is displayed in the field selection dialog metadata. Some metadata attributes of a field are presented in a tool tip box when you hover over the field name.

Embedded blanks are permitted in a value for an alphanumeric field. When entering a value for an alphanumeric field, single quotes are not required, and if used they will be treated as data.
Since a comma is used to create an OR condition, if the alphanumeric value you are testing for contains a comma, or begins with a double quote, use double quotes to delimit the value you are looking for. Examples: A,B tests for A or B; "A,B" tests for A,B; A," tests for A or "; ",A is an error (a value starting with a double quote must end with a double quote and will test for anything between the double quote delimiters); "",A" tests for ",A.

For numeric data types (Binary (B), Numeric (N), Packed (P)) in unformatted sets and conditions, all values must be entered as signed or unsigned integers; no decimal points are allowed. In addition, the length of the number you enter must not exceed the length of the field you specify.

For Bit mask (M), you may enter 2 hex digits (0-9,A-F) or 8 binary digits (0-1), and you may use the comma to provide a list of values. (Examples: FF; 11111111; 0F,70 (hex 0F or hex 70).
For Hex (X), you may enter pairs of 2 hex digits (0-9,A-F) not to exceed the length of the field. You may use the comma to provide a list of values. (Examples: FFFF; AB0000FF; 000C,F1F2 (hex 000C or hex F1F2).

Choose Field Mode

When you provide a Single record layout while working with z/OS files, you must select the type of fields you want to use to define conditions for a set.

Note

When using a Record layout cross reference (XREF), all conditions are implicitly Unformatted mode defined with the User Defined Field dialog.

To Define Conditions for a Set

  1. Access the Choose Field Mode dialog box by clicking Add Set from the Conditions tab of the File-AID Data Editor Request window.

  2. Choose whether to use a Formatted or Unformatted mode in the data editor.
    Formatted mode specifies that you have a layout file for this condition.
    Unformatted mode specifies that you do not have a layout file for this condition and will navigate to the User Defined Field dialog box where you can define your field.

    Note

    The choice for formatted or unformatted mode only appears for the first condition that you create for a specific set. If you create a new set, you will again choose whether to use formatted or unformatted mode.

  3. After making your selection, click OK. You will return to the File-AID Data Editor Request window. For more information, see Requesting z/OS Datasets.

User Defined Field

The User Defined Field dialog box defines conditions for selecting MVS data without using a record layout.
You can access the User Defined Field dialog box by clicking Add Set on the Condition tab of the File-AID Data Editor Request window. If you have provided a Single record layout, the Choose Field Mode dialog appears. Choose Unformatted criteria to access the User Defined Field dialog box.

To Specify a User-defined Field

  1. In the Field column, click on <select field>. The User Defined Field dialog box appears.
  2. Enter the Location for this field.
  3. Enter the Field length. This field is required when searching for binary numeric data using the Binary (B) data type and must be either 1, 2, 4, or 8. If a length is not specified with the contains operator, it implies to scan from the specified location to the end of the record.
  4. Select a Data Type: Choices include:
    1.  Any Case Text (T) (default): The values entered are used to compare with the data at the specified location and will match any case (upper, lower, or mixed) of the entered strings.
    2.  Exact Case Text (C): The values entered are used to compare with the data at the specified location and will match only the exact case of the entered strings.
    3.  Hex (X): The value is expected to be one or more even pairs of hex digits 0-9, A-F. The values entered are used to compare with the data at the specified location and will match the hex values of the data in the record.
    4.  Packed (P): Typically the value entered is a signed or unsigned decimal integer. It is used to compare with the data at the location in packed format. If the value entered is unsigned or positive, it will match a positive or an unsigned packed number at the specified location. If negative, it will only match a negative packed number at the specified location.
    5. Binary (B): Similar to the Packed (P) data type, the value entered is a signed or unsigned decimal integer. A length (1, 2, 4, or 8) is required with this data type. The value entered is converted to a binary value and compared to the binary data at the specified location.
    6. Numeric (N): Typically the value entered is a signed or unsigned decimal integer. It is used to compare with the data at the location in zoned numeric format where the sign is in the last byte. If the value entered is unsigned or positive, it will match a positive or an unsigned zoned numeric number at the specified location. If negative, it will only match a negative zoned numeric number at the specified location.
    7. Bit Mask (M): This data type tests for individual bits in one byte of data at the specified location. The value specified is a pair of hex digits 0-9, A-F. Example: FF is a binary mask equivalent to 11111111. Special operators are provided when using this data type: is equal to (all ones, all 1s in the mask are on in the data), is not equal to (not ones, all 1s in the mask are off in the data), are mixed ones and zeros (some 1s, but not all, in the mask are on in the data), are not ones (not all 1s in the mask are on in the data). The operators are mixed ones and zeros and are not ones are only used when the bit mask contains more than one 1 and have no meaning if there is only 1 bit to test. When the mask has only one bit, the operator is equal to is the same as are mixed ones and zeros, and the operator is not equal to is the same as are not ones.
  5. Select the desired Operator. The available operators depend on the data type chosen. Not all operators are available for every data type. For more information, see z/OS Selection Criteria Operators.
  6. Enter the desired Value.
    For the operators is equal to, is not equal to, contains, and does not contain, you can enter a single value or you can enter multiple values separated by a comma. This means that any of the specified values will be a match.
    Since a comma is used to create an OR condition, in order to specify a condition where the value contains a comma, you must enter a double quote (") delimited value containing a comma, for example "find,the,comma". Any data enclosed in a pair of double quotes will be considered one value, not a list of multiple values. When using double quotes, you cannot specify multiple values separated by commas. Using double quotes allows you to search for strings containing commas, apostrophes, and even double quotes. Values beginning with a double quote must end with a double quote. The double quote delimiters at the beginning and end of the value are not included in the search value. For more information, see z/OS Values.
    If you supply apostrophe (single quote) delimiters in the value, they will be considered part of the value. For example, a value of 'A,B' means 'A or B'. Apostrophes are not required, and if entered are considered to be data you are trying to find.
    For the is between and is not between operators, you must enter two values separated by a colon (:). For numeric data types (P, B, N) the is a valid field and is an invalid field operators do not use a value and should be left blank.
    For Packed, Numeric, and Binary values, no punctuation (decimals or commas) are permitted in the value.
    For Binary, values may be signed or unsigned decimal numbers within the range allowed for the length. For example with a length of 1 you may look for values in the range of (signed) -127 to +127 or (unsigned) 0 to 255. With a length of 2 you may look for values in the range of (signed) -32767 to +32767 or (unsigned) 0 to 65535. With a length of 4 you may look for values in the range of (signed) -2147483647 to +2147483647 or (unsigned) 0 to 4294967295. With a length of 8 you may look for values in the range of (signed) -999999999999999999 to unsigned or +999999999999999999 (18 digit number).
    For Packed fields, a length is optional when specifying a value. File-AID will attempt to find a packed field of any length at the location specified. If a record does not contain a valid packed field of any length at the specified location, the record will not match the condition and will be counted as an error. If a length is specified, the number of digits you provide in the value must not exceed the length based on the formula digits = Length * 2 - 1. For example a length of 3 means a maximum value of -99999 thru +99999 (5 digits: 3 times 2 = 6 minus 1 = 5).
  7. Click OK to return to the File-AID Data Editor Request window.

Select Filter Field

The Select Filter Field dialog box allows you to select the field to use for the formatted condition you are defining. You can choose only one field per condition.

You can access the Select Filter Field dialog box by clicking <select field> in a new condition or clicking on a field name in an existing condition.

To Access the Select Filter Field

  1. In the Field column, click on <select field>. The Select Filter Field dialog box appears.
  2. Select the desired field by clicking the desired field name. The search box near the top can be used to quickly find the desired field.
  3. Click OK to return to the File-AID Data Editor Request window to complete your condition.

 

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