Dataset Services Interface › $DSCALL OPT=READ

$DSCALL OPT=READ

Reads one or more records from a data set.

&CONTROL SHRVARS=($DS)
EXEC $DSCALL OPT=READ 
             DATA= { * | variable_name [ , variable_name,... ] | prefix*} 
           { DD=DD_name | ID=path_name } 
           [ LIMIT= number ] 
           [ TRUNCATE= number ]

This option is used to read records from a data set or a member of a PDS into variables. The procedure must have an open path to the data set or PDS member to be read (use $DSCALL OPT=OPEN to open a path).

Operands:

• OPT=READ

  Specifies that a read action be performed.

• DATA={ * | variable_name [ , variable_name... ] | prefix*}

  Specifies the records to be read.

  • If DATA=* is specified, the records are returned in a shared variable, &$DSDATA*. All records are read until the LIMIT value is reached or the end of file (EOF) is reached. The records are placed in variables called &$DSDATA1, &$DSDATA2, and so on as required. If the LIMIT operand is omitted, a value of 1 is assumed.
  • If DATA=variable_name is specified, a single record is read. Multiple variables need to be specified (variable_name1,variable_name2,...,variable_namen) when the record is longer than 250 bytes and must be divided into 250-byte segments. In this case, the relevant variables must be included in SHRVARS with the $DSCALL procedure. The variable name cannot have prefix $DS; if it does, it is reset to null.

    Note: This version of the DATA operand reads only one record into the data set. It must be used to read records containing more than 250 bytes.

  • If DATA=prefix* is specified, the records are returned in shared variables &prefix1, &prefix2, and so on, as required. All records are read until the LIMIT value is reached or the end of file (EOF) is reached. If the LIMIT operand is omitted, a value of 1 is assumed.
• DD=DD_name

  Specifies the ddname of the file to be read. This operand is used as the path ID if the ID parameter is not set. The path ID specified must already have been created with an OPT=OPEN or OPT=FOPEN call.

• ID=path_name

  Specifies the path ID of the file to be read.

  Note: Any combination of OPEN, FOPEN, CLOSE, FCLOSE, READ, and WRITE requests must be done in a single procedure.

• LIMIT=number

  Specifies the maximum number of records to be read from the file. The value of the LIMIT operand must be in the range 1 to 9,999. This operand is applicable only if DATA=* or DATA=prefix* is specified.

• TRUNCATE=number

  Specifies the length to which records read from the file are truncated. The value of the TRUNCATE operand must be in the appropriate range for the value specified for the DATA operand:

  • If DATA=* or DATA=prefix* is specified, then the TRUNCATE value must be in the range 1 to 250.
  • If DATA=variable_name1,variable_name2,...,variable_namen is specified, then the TRUNCATE value must be in the range 1 to 32,760.

Return Codes:

Note: For more information about &SYSMSG, &$DSRC, and &$DSFDBK, see Return Codes and Feedback Codes.

$DSFDBK is set to 9 and $DSRC set to 4 if the number of records specified by the LIMIT operand is not satisfied.

Return Variables:

• &$DSDATAn

  Contains the records for the DATA=* option, where n is a number to identify each return. If the DATA=variable_name operand is used, the nominated variables contain the data

• &$DSDATA#

  Contains the count of records read. For DATA=* it contains the number of records read on this call.

• &$DSEOF

  End of file indicator. The value is null unless the end of file is encountered. If end of file is encountered, this variable is set to the value EOF. If DATA=variable_name is specified, no data is returned if the end of file is encountered.

Examples: OPT=READ

&CONTROL SHRVARS=($DS)
EXEC $DSCALL OPT=READ ID=SYSPATH DATA=* +
   LIMIT=9999

&CONTROL SHRVARS=($DS, ABC)
EXEC $DSCALL OPT=READ ID=SYSPATH DATA=ABC

&CONTROL SHRVARS=($DS, ABC)
EXEC $DSCALL OPT=READ ID=SYSPATH +
   DATA=ABC* LIMIT=9999