&FILE SET

Verbs and Built-in Functions › &FILE SET

&FILE SET

The &FILE SET verb specifies or switches file records.

This verb has the following format:

&FILE SET ID=fileid
        [ KEY=key | KEYVAR=keyvar ]
        [ GENLEN=nn ]
        [ FORMAT={ MAPPED | UNMAPPED | DELIMITED } ]
        [ MAP={ $NCL | mapname } ]

Operands:

ID=fileid

Identifies the file.

KEY=key

Specifies the full key value to set for the file. The key value (after substitution) is in one of several forms:

An unquoted character string (no embedded blanks), for example:
```
01SMITH
```
For unquoted strings, the key consists of displayable characters only, and the first blank delimits it.
A quoted character string, for example:
```
'01SMITH J.'   “03JONES PETER A”    “LU A0123BC2”C 'A. B. O''MALLEY'C
```
The usual quote rules apply. Either single quotes (') or double quotes (”) are acceptable. Quotes must be paired and of the same type. A double quote is treated as a single quotation character when included within a string.
A quoted hexadecimal character string, for example:
```
'0012001F'X
```
```
“0123456789ABCDEF”X
```

If there are no characters following the closing quote, a character string is assumed. If a single character follows the closing quote then it must be either 'C' (designating a character string), or 'X' (designating a hexadecimal string). For quoted hexadecimal strings, all characters must be valid hexadecimal characters (that is, 0 through 9 and A through F).

The user is responsible to understand the file key structure and determine which form of key designation is most appropriate.

Note: The &ZQUOTE built-in function can assist when building quoted strings, and that the KEYVAR operand provides a suitable alternative.

KEYVAR=keyvar

Provides an alternative way to nominate the full key value. keyvar is the name of a user or system variable, the contents of which are taken unchanged as the key value for the file set operation. The ampersand (&) is not required—if the & is coded, then the contents of the variable specified are assumed to contain the name of the variable containing the key.

If both the KEY and KEYVAR operands are omitted, the current file key value is used.

GENLEN=nn

Allows the generic key length for operations such as generic read, and generic delete, to be set independently of the actual key value. For example, by setting the key to 01SMITH, but GENLEN=2, &FILE GET OPT=KEQ begins reading from the key but terminates if any key encountered does not begin with 01. If the length of the key provided is shorter than the value of GENLEN, then the length of the key is the effective GENLEN.

FORMAT={ MAPPED | UNMAPPED | DELIMITED }

Allows the switching of the file processing format. The options are as described for the &FILE OPEN statement. No default applies to the &FILE SET statement. If the FORMAT operand is omitted, there is no change to the processing format.

MAP={ $NCL | mapname }

Valid only if FORMAT=MAPPED is specified explicitly on the &FILE SET or if the current processing is for format MAPPED. The meaning is as described for the &FILE OPEN statement.

Return Codes:

On completion of the operation, the &FILERC system variable is set as follows:

0: Record added successfully
16: NCL or Mapping Services processing error (see &SYSMSG for details)

More information:

&FILE