CA-Datamacs/II CA-DATACOM/DB Interface › CA-Datamacs/II CA-DATACOM/DB Interface Statements › READ

READ

The purpose of the READ statement is to cause data transfer from the database table into a unique table input work area. This READ command only issues record-at-a-time commands, and is functionally equivalent to CA-DATACOM/DB's READ commands, with extensions unique to CA-Datamacs/II.

READ  [(AND) HOLD]
        {BACK | GE | LE | EQ | RANGE | LOCATED |
         NEXT-SEQ-INDEX |  NEXT-EQ   | NEXT-RANGE | NEXT-UNIQUE}
 
         table-name
 
        [KEY NAME IS   key-occurrence-name]
 
        [{USING KEY         key-value1|
         USING KEY RANGE   key-value1,key-value2|
         USING {ddname|dtfname} AS INPUT}]
 
        [NOT-FOUND     GO TO {paragraph-name | GOBACK | FINISH}
         AT-END        GO TO {paragraph-name | GOBACK | FINISH}
         KEYS-AT-END   GO TO {paragraph-name | GOBACK | FINISH}]
        [ON-DB-ERROR  {EQ|GT|LT|NE}  'db-error-code'
                       GO TO {paragraph-name | GOBACK | FINISH}]
 
        [WHEN  conditional-clause   USE table-name].

HOLD

HOLD is used to establish exclusive control when a subsequent UPDATE or DELETE command is issued against the record.

BACK

Retrieves records backwards from a previously established table location.

GE

Retrieves a record with a key value greater than or equal to the key value specified.

LE

Retrieves a record with a key value less than or equal to the key value specified.

EQ

Retrieves a record with a key value equal to the key value specified.

LOCATED

Retrieves the actual data after the record was located by a previous LOCATE command.

RANGE

Retrieves the first record within a range of key values.

NEXT-RANGE

Retrieves the next record in a previously established range of key values.

NEXT-UNIQUE

Retrieves the next sequentially unique record .

NEXT-EQ

Retrieves the next record with a key value equal to the key value specified.

NEXT-SEQ-INDEX

Retrieves the next record based on the next sequential index entry.

table-name

Specify the 1-to-32 character table occurrence name which must match a table name on a COPY TABLE statement.

KEY NAME IS

This entry identifies the Datadictionary 1-to-32 character key occurrence name to be used. If this keyword is not entered, the key name from the COPY TABLE statement is used, or if no KEY NAME is specified, it will default to the first master key name related to this table as defined in Datadictionary.

USING KEY xxxxxxxx and USING KEY RANGE xxxxxxxx,yyyyyyyy

Identifies a key literal to be used when a single record or a range of records is to be retrieved. The maximum length of an individual key literal is that which can be coded within area B of the COBOL statement. See the function logic MOVE statement for more syntax rules concerning literals.

Numeric literals should be entered without any periods or commas. A trailing minus sign can be used to indicate a negative number. Alphanumeric literals should be enclosed in quotes. Any trailing blanks should be included in quotes. A hex value can be entered by enclosing the value with X'value'. Only valid hexadecimal digits are allowed; 0 to 9 and A to F. Packed numeric values should be entered as hex values, insuring the same sign is used as that specified in Datadictionary.

When a second key value must be entered to identify the range of a command, add the identifying keyword RANGE.

USING ddname/dtfname AS INPUT

Multiple key values can be stored in a sequential input file (QSAM for MVS) with a minimum record size of 80 bytes and a maximum record size of 256 bytes. This allows room for the required delimiter characters (for example, apostrophes for alpha, and so forth). Each key literal in one record must be separated by at least 1 space. Any mix of alpha, numeric, and hex is allowed. This entry specifies the file name of the data set. Seventeen key data sets are allowed with file names of DMIKEYS and DMIKY01 to 16.

For a command requiring a key value range, the second key value should be placed in a second record immediately following the first record. Basically, two key records would be required for one READ range command.

There is no requirement for the keys file record size to match the key occurrence length as specified in Datadictionary. Partial keys are supported but key values longer than the key occurrence length will be rejected.

Only one USING statement can be used per READ command.

NOT-FOUND

Specify a paragraph name to branch to when the key is not found, the end of a range of keys is reached, or the next equal key was not found. The CA-DATACOM/DB return code 14 activates this option. FINISH is an internal paragraph name which will cause the job to end. The GOBACK option is only used when a READ command has been executed because it is in a paragraph PERFORM'd by the CA-Datamacs/II EQUI-JOIN command. If the key is not found, specifying GOBACK will cause a return to the EQUI-JOIN command.

AT-END

Specify the paragraph name to branch to when the end of a key range is reached, or end of table is reached.

KEYS-AT-END

Specify the paragraph name to branch to when the input keys file reaches end of file. This option can only be used in conjunction with the USING {ddname|dtfname} AS INPUT option.

ON-DB-ERROR

For the everyday use of CA-Datamacs/II it is not necessary to directly know the low level DB error return codes. However, in the event it becomes necessary to test for a specific error code, this option will be triggered when the logic operator is evaluated as true. Be aware, if coded, the NOT-FOUND and AT-END options will be triggered first.

WHEN

Can be used to further qualify a record for selection by testing any field in the record for specific criteria. The WHEN must be placed after all other keywords. If the WHEN is used with a READ EQ, and the WHEN test fails, the NOT-FOUND option will be activated. Otherwise, the WHEN test would be applied until a match occurs or the end of the process occurs, at which time the AT-END option will be activated.

Programming Notes:

The READ command is global in the sense that it presumes a combination of functions. If a prerequisite command is necessary it will do it automatically. The READ command can be used with the CREATE, manual LOAD, UNLOAD, and MODIFY functions.

The following chart depicts the actual native record-at-a-time commands that the various READ options are converted to.