For text files: FILE HANDLE handle_name /NAME='file-name' [/MODE=CHARACTER] /TABWIDTH=tab_width For binary files in native encoding with fixed-length records: FILE HANDLE handle_name /NAME='file-name' /MODE=IMAGE [/LRECL=rec_len] For binary files in native encoding with variable-length records: FILE HANDLE handle_name /NAME='file-name' /MODE=BINARY [/LRECL=rec_len] For binary files encoded in EBCDIC: FILE HANDLE handle_name /NAME='file-name' /MODE=360 /RECFORM={FIXED,VARIABLE,SPANNED} [/LRECL=rec_len]
Use FILE HANDLE to associate a file handle name with a file and its attributes, so that later commands can refer to the file by its handle name. Names of text files can be specified directly on commands that access files, so that FILE HANDLE is only needed when a file is not an ordinary file containing lines of text. However, FILE HANDLE may be used even for text files, and it may be easier to specify a file's name once and later refer to it by an abstract handle.
Specify the file handle name as the identifier immediately following the FILE HANDLE command name. The identifier INLINE is reserved for representing data embedded in the syntax file (see BEGIN DATA) The file handle name must not already have been used in a previous invocation of FILE HANDLE, unless it has been closed by an intervening command (see CLOSE FILE HANDLE).
The effect and syntax of FILE HANDLE depends on the selected MODE:
In CHARACTER mode only, tabs are expanded to spaces by input programs, except by DATA LIST FREE with explicitly specified delimiters. Each tab is 4 characters wide by default, but TABWIDTH (a PSPP extension) may be used to specify an alternate width. Use a TABWIDTH of 0 to suppress tab expansion.
Alphanumeric data in mode 360 files are encoded in EBCDIC. PSPP translates EBCDIC to or from the host's native format as necessary on input or output, using an ASCII/EBCDIC translation that is one-to-one, so that a “round trip” from ASCII to EBCDIC back to ASCII, or vice versa, always yields exactly the original data.
The RECFORM subcommand is required in mode 360. The precise file format depends on its setting:
IBM documentation calls this *F
(fixed-length, deblocked)
format.
Following the BDW, the remainder of each block is a sequence of one or more variable-length records, each of which in turn begins with a 4-byte record descriptor word (RDW) that has the same format as the BDW. Following the RDW, the remainder of each record is the record data.
The maximum length of a record in VARIABLE mode is 65,527 bytes: 65,535 bytes (the maximum value of a 16-bit unsigned integer), minus 4 bytes for the BDW, minus 4 bytes for the RDW.
In mode VARIABLE, LRECL specifies a maximum, not a fixed, record length, in bytes. The default is 8,192.
IBM documentation calls this *VB
(variable-length, blocked,
unspanned) format.
The maximum length of a logical record in VARIABLE mode is limited only by memory available to PSPP. Segments are limited to 65,527 bytes, as in VARIABLE mode.
This format is similar to what IBM documentation call *VS
(variable-length, deblocked, spanned) format.
In mode 360, fields of type A that extend beyond the end of a record
read from disk are padded with spaces in the host's native character
set, which are then translated from EBCDIC to the native character
set. Thus, when the host's native character set is based on ASCII,
these fields are effectively padded with character X'80'
. This
wart is implemented for compatibility.
The NAME subcommand specifies the name of the file associated with the handle. It is required in all modes but SCRATCH mode, in which its use is forbidden.