Specifying File Key Lists in I/O Commands

Many of the LANSA database I/O commands allow the specification of a file key. In all cases the method and logic used to set up the file key is identical.

The following points should be noted about specifying file keys:

• The order that the key fields are specified on the command is as important as the content of the key fields.

• The key field nominated does not have to (and often will not) have the same name as the matching key field. The key fields nominated in the command are matched in the order specified with the actual key fields of the file.
  
  For example, if #ORDNUM contains 123456 and #LINENO contains 1, then this command will attempt to fetch the first record in file ORDLIN with an order number = 123456 and a line number = 1:

       FETCH   FROM_FILE(ORDLIN) WITH_KEY(#ORDNUM #LINENO)

       If, however, the command is specified as then LANSA will attempt to fetch the first record in file ORDLIN with an order number = 1 and a line number = 123456:

     FETCH   FROM_FILE(ORDLIN) WITH_KEY(#LINENO #ORDNUM)

       This is because the actual file keys are "order number" followed by "line number". LANSA processes the key fields nominated, by matching their position with the actual file keys, not by their names.

• The key field nominated does not have to have the same length as the key field in the file. LANSA will automatically adjust the lengths as required. However, the key field nominated and the actual file key field must be of the same type (alphanumeric or numeric).

• Most commands support the use of "partial" keys. For instance if a file is keyed by KEY01, KEY02 and KEY03 it is possible to use the following variations:

       KEY01  KEY02  KEY03

       or KEY01  KEY02

       or KEY01

        but, it is not possible to specify:

     -----  -----  KEY03

     or -----  KEY02  KEY03

     or KEY01  -----  KEY03

• Expandable group expressions are allowed in key lists. The number of entries in the expanded list must match in type and must not exceed the number of fields in the key list of the file.

• When the key list contains date, time or timestamp fields, the nominated key fields must have valid date, time or timestamp values. LANSA will validate these fields and return an error if invalid values are nominated.

Further Information

I/O Command Return Codes Table

I/O Status Record Locked