&FILE PUT

Verbs and Built-in Functions › &FILE PUT

&FILE PUT

The &FILE PUT verb puts a file record.

This verb has the following format:

&FILE PUT 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

(Mandatory) Identifies the file being actioned.

KEY=key

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

An unquoted character string (no imbedded blanks). For example:
```
01SMITH
```
For unquoted strings the key should consist of displayable characters only, and is delimited by the first blank.
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 to 9, A to F).

It is the user's responsibility 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. There is no need to code the ampersand (&)—if the & is coded, then the contents of the variable specified are assumed to contain the name of the variable containing the key.

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

OPT={ TRUNCATE | NOTRUNCATE }

Indicates whether or not to allow truncation of data on an &FILE PUT. If NOTRUNCATE is specified (or defaulted), the procedure will end 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 PUT operation. NCL variables are validly used as the source of the PUT 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 be written to the file. NCL variables are validly used as the source of the PUT 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 to be placed within 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 PUT operation. An MDO is the source of the data record on a PUT operation only when the file format is MAPPED.

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

If FILE PUT 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.

Multiple options is 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 is the default value 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 to be used 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, which is specified in the LRECL operand of the ALLOC command (for z/OS or MSP).
BOLD: Prints the text in bold form. This is achieved by overstriking 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
8: Error during processing of PUT 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 always returned as a 2-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.

More information:

&FILE