&FILE ADD

Verbs and Built-in Functions › &FILE ADD

&FILE ADD

The &FILE ADD verb adds a file record.

This verb has the following format:

&FILE ADD ID=fileid
        [ KEY=key | KEYVAR=keyvar ]
        [ OPT={ TRUNCATE | NOTRUNCATE } ]
        [ { ARGS | VARS=prefix* } [ RANGE=(start,end) ] |
            VARS={ var | ( var1,var2,...,varn )|
            DATA=data | MDO=mdoname ]
        [ PRTCNTL=opt | (opt1,opt2 [ ,opt3,opt4 ] ) ]

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.

OPT={ TRUNCATE | NOTRUNCATE }

Specifies whether to allow truncation of data on an &FILE ADD. If NOTRUNCATE is specified (or defaulted), the procedure ends, with an error message, if the data exceeds the maximum record length of the file. When TRUNCATE is specified, a file return code of 1 is set if truncation occurs.

{ ARGS | VARS=prefix* } [ RANGE (start,end) ]

Nominates the NCL variables for the ADD operation. NCL variables are validly used as the source of the ADD operation when the file format is DELIMITED or UNMAPPED, and when the format is MAPPED and MAP=$NCL. How the variable appears on the file depends upon the current processing mode (format). If the format is UNMAPPED, then the variables are simply concatenated to form the record. If the format is DELIMITED, the variables are placed on the file separated by X'FF' separators.

VARS={ var | ( var1,var2,...,varn ) }

Specifies the list of variables to write to the file. NCL variables are validly used as the source of the ADD operation when the file format is DELIMITED or UNMAPPED, and when the format is MAPPED and MAP=$NCL.

DATA=data

Data is allowed for DELIMITED or UNMAPPED format files only, and specifies a string of data for the file record. Substitution occurs on the specified string of data, and then the data is placed on the record as is.

MDO=mdoname

Nominates the MDO for the ADD operation. An MDO is the source of the data record on an ADD operation only when the file format is MAPPED.

PRTCNTL=opt | (opt1,opt2 [ ,opt3,opt4 ] )

If FILE ADD writes to OS/VS SYSOUT data sets, use PRTCNTL to specify carriage control options to control print formatting. Print format categories are as follows:

Paper movement—SKIP0, SKIP1, SKIP2, SKIP3, NEWPAGE, and DATA
Underscoring—USCORE1 and USCORE2
Text alignment—LEFT, RIGHT, and CENTER
Bold print—BOLD

One option from each of these categories is specified.

Note: Multiple options are specified, but they must be enclosed in parentheses and separated by commas. For example:

PRTCNTL=(NEWPAGE,USCORE1,CENTER,BOLD)

SKIP0: Does not advance the paper before writing the record.
SKIP1: Advances the paper one line before writing the record. When writing records to OS/VS SYSOUT data sets, this value is the default if the PRTCNTL operand is omitted.
SKIP2: Advances the paper two lines before writing the record.
SKIP3: Advances the paper three lines before writing the record.
NEWPAGE: Skips to a new page before writing the record.
DATA: Indicates that the first text character contains the carriage control character for controlling the print options for printing this record. If machine control characters are used (instead of ANSI control characters), DATA is the only carriage control option allowed.
USCORE1: Underlines the text for this record (excluding blanks between words).
USCORE2: Underlines the text for this record including blanks between words.
LEFT: Aligns the text for this record to the left of the paper.
RIGHT: Aligns the text for this record to the right of the paper.
CENTER: Centers the text for this record. The record width, and therefore the location of the center, is determined from the logical record length of the file. The length is specified in the LRECL operand of the ALLOC command (for z/OS or MSP).
BOLD: Prints the text in bold form. Bold is achieved by overprinting the same characters.

Return Codes:

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

0: record added successfully
1: record added, truncation has occurred
4: record exists
8: error during processing of ADD request
16: NCL or Mapping Services processing error

Check &SYSMSG for details. The &VSAMFDBK system variable contains the VSAM completion code. For &FILERC=8, the &VSAMFDBK system variable is tested to determine the cause of the error. These error codes are explained in detail in your VSAM documentation. The &VSAMFDBK variable is always returned as a two-character value.

The &SYSMSG variable can also be set to contain error message details.

For mapped format files, the &ZMDORC and &ZMDOFDBK system variables are also set.