Specifies the current output file for PUT statements
| Valid: |
in a DATA step
|
| Category: |
File-handling
|
| Type: |
Executable
|
|
FILE file-specification <options>
<host-options>;
|
-
file-specification
-
identifies an external file that the DATA
step uses to write output from a PUT statement. File-specification can have these forms:
-
'external-file'
-
specifies the physical name of an external
file, which is enclosed in quotation marks. The physical name is the name
by which the operating environment recognizes the file.
-
fileref
-
specifies the fileref of an external file.
-
fileref(file)
-
specifies a fileref that is previously assigned
to an external file that is an aggregate grouping of files. Follow the fileref
with the name of a file or member, which is enclosed in parentheses.
Operating Environment Information:
Different
operating
environments call an aggregate grouping of files by different names, such
as a directory, a MACLIB, or a partitioned data set. For details, see the
SAS documentation for your operating environment. ![[cautend]](../common/images/cautend.gif)
-
LOG
-
is a reserved fileref that directs the output
that is produced by any PUT statements to the SAS log.
At the beginning of each execution of a DATA step, the
fileref that indicates where the PUT statements write is automatically set
to LOG. Therefore, the first PUT statement in a DATA step always writes to
the SAS log, unless it is preceded by a FILE statement that specifies otherwise.
-
PRINT
-
is a reserved fileref that directs the output
that is produced by any PUT statements to the same print file as the output
that is produced by SAS procedures.
Operating Environment Information:
The carriage control
characters that are written to a file can be specific to the operating environment.
For details, see the SAS documentation for your operating environment. ![[cautend]](../common/images/cautend.gif)
-
BLKSIZE=block-size
-
specifies the block size of the output file.
Operating Environment Information:
The
default value of
the block size is dependent on the operating environment. For details, see
the SAS documentation for your operating environment. ![[cautend]](../common/images/cautend.gif)
-
COLUMN=variable
-
specifies a variable that SAS automatically
sets to the current column location of the pointer. This variable, like automatic
variables, is not written to the data set.
-
DELIMITER= 'quoted
string'
| character_variable
-
specifies an alternate delimiter (other
than blank) to be used for LIST output. It is ignored for other types of output
(formatted, column, named).
-
DROPOVER
-
discards data items that exceed the output
line length (as specified by the LINESIZE= or LRECL= options in the FILE statement).
-
DSD
-
enables you to write data items that contains
embedded delimiters to LIST output. It is ignored for other types of output
(formatted, column, named). Any data item that contains the specified delimiter
is quoted with the double quotation mark (") as it is output. Any double
quotation marks that are embedded in the data item are promoted. For example,
the data item, Dad"s, is written as "Dad" "s" in LIST output.
-
FILENAME=variable
-
defines a character variable, whose name
you supply, that SAS sets to the value of the physical name of the file currently
open for PUT statement output. The physical name is the name by which the
operating environment recognizes the file.
-
FILEVAR=variable
-
defines a variable whose change in value
causes the FILE statement to close the current output file and open a new
one the next time the FILE statement executes. The next PUT statement that
executes writes to the new file that is specified as the value of the FILEVAR=
variable.
-
FLOWOVER
-
causes data that exceed the current line
length to be written on a new line. When a PUT statement attempts to write
beyond the maximum allowed line length (as specified by the LINESIZE= option
in the FILE statement), the current output line is written to the file and
the data item that exceeds the current line length is written to a new line.
-
FOOTNOTES | NOFOOTNOTES
-
controls whether currently defined footnotes
are printed.
-
HEADER=label
-
defines a statement label that identifies
a group of SAS statements that you want to execute each time SAS begins a
new output page.
-
LINE=variable
-
defines a variable whose value is the current
relative line number within the group of lines available to the output pointer.
You supply the variable name; SAS automatically assigns the value.
-
LINESIZE=line-size
-
sets the maximum number of columns per line
for reports and the maximum record length for data files.
-
LINESLEFT=variable
-
defines a variable whose value is the number
of lines left on the current page. You supply the variable name; SAS assigns
that variable the value of the number of lines left on the current page. The
value of the LINESLEFT= variable is set at the end of PUT statement execution.
-
LRECL=logical-record-length
-
specifies the logical record length of the
output file.
Operating Environment Information:
Values
for logical-record-length are dependent on the operating environment.
For details, see the SAS documentation for your operating environment.
-
MOD
-
writes the output lines after any existing
lines in the file.
-
N=available-lines
-
specifies the number of lines that you want
available to the output pointer in the current iteration of the DATA step. Available-lines can be expressed as a number (n) or as the keyword
PAGESIZE or PS.
-
n
-
specifies the number of lines that are available
to the output pointer. The system can move back and forth between the number
of lines that are specified while composing them before moving on to the next
set.
-
PAGESIZE
-
specifies that the entire page is available
to the output pointer.
-
NBYTE=variable
-
specifies the name of a variable that contains
the number of bytes to write to a file when you write data in stream record
format (RECFM=S in the FILENAME statement). By default, the number of bytes
that are read is equal to the actual LRECL value of the file. NBYTE= is used
with the SOCKET and FTP access methods only.
-
ODS < = (ODS suboptions)
>
-
specifies to use the Output Delivery System
to format the output from a DATA step. It defines the structure of the data
component and binds that component to a table definition to produce an output
object. ODS sends this object to all open ODS destinations, each of which
formats the object appropriately. For information on the ODS
suboptions, see ODS Suboptions.
For general information on the Output Delivery System, seeThe Complete
Guide to the SAS Output Delivery System.
| Default: |
If you omit the ODS
suboptions, the DATA step uses a default table definition (base.datastep.table)
that is stored in the SASHELP data library. This definition defines two generic
columns: one for character variables, and one for numeric variables. ODS associates
each variable in the DATA step with one of these columns and displays the
variables in the order in which they are defined in the DATA step.
Without suboptions, the default table definition uses
the variable's label as its column header. If no label exists, the definition
uses the variable's name as the column header. |
| Requirement: |
The ODS option is
valid only when you use the fileref PRINT in the FILE statement. |
| Restriction: |
You cannot use the
_FILE_=, FILEVAR=, HEADER=, and PAD options with the ODS option. |
| Interaction: |
The DELIMITER= and
DSD options have no effect on the ODS option. The FOOTNOTES|NOFOOTNOTES, LINESIZE,
PAGESIZE, and TITLES | NOTITLES options only have an effect on the listing
destination. |
-
OLD
-
replaces the previous contents of the file.
-
PAD
| NOPAD
-
controls whether records written to an external
file are padded with blanks to the length that is specified in the LRECL=
option.
-
PAGESIZE=value
-
sets the number of lines per page for your
reports.
-
PRINT | NOPRINT
-
controls whether carriage control characters
are placed in the output lines.
Operating Environment Information:
The
carriage control
characters that are written to a file can be specific to the operating environment.
For details, see the SAS documentation for your operating environment. ![[cautend]](../common/images/cautend.gif)
-
RECFM=record-format
-
specifies the record format of the output
file.
Operating Environment Information:
Values
for record-format are dependent on the operating environment.
For details, see the SAS documentation for your operating environment. ![[cautend]](../common/images/cautend.gif)
-
STOPOVER
-
stops processing the DATA step immediately
if a PUT statement attempts to write a data item that exceeds the current
line length. In such a case, SAS discards the data item that exceeds the current
line length, writes the portion of the line that was built before the error
occurred, and issues an error message.
-
TITLES | NOTITLES
-
controls the printing of the current title
lines on the pages of print files. When NOTITLES is omitted, or when TITLES
is specified, SAS prints any titles that are currently defined.
-
_FILE_=variable
-
names a character variable that references
the current output buffer of this FILE statement. You can use the variable
in the same way as any other variable, even as the target of an assignment.
The variable is automatically retained and initialized to blanks. Like automatic
variables, the _FILE_= variable is not written to the data set.
Operating Environment Information:
For
descriptions of
host-specific options on the FILE statement, see the SAS documentation for
your operating environment.
By default, PUT statement output is written to the SAS
log. Use the FILE statement to route this output to either the same external
file to which procedure output is written or to a different external file.
You can indicate whether or not carriage control characters should be added
to the file. See the PRINT | NOPRINT option .
You can use the FILE statement in conditional (IF-THEN)
processing because it is executable. You can also use multiple FILE statements
to write to more than one external file in a single DATA step.
Operating Environment Information:
Using the FILE
statement requires host-specific information.
See the SAS documentation for your operating environment before you use this
statement.
You can now use the Output Delivery System with the
FILE statement to write DATA step results. This functionality is briefly discussed
here. For details, see FILE, ODS.
For further information, see The Complete Guide to the SAS Output Delivery
System.
You can use the FILE statement with the INFILE and PUT
statements to update an external file in place, updating either an entire
record or only selected fields within a record. Follow these guidelines:
In addition to the _FILE_= variable, you can use the
automatic _FILE_ variable to reference the contents of the current output
buffer for the most recent execution of the FILE statement. This character
variable is automatically retained and initialized to blanks. Like other automatic
variable, _FILE_ is not written to the data set.
When you specify the _FILE_= option in a FILE statement
then this variable is also indirectly referenced by the automatic _FILE_
variable. If the automatic _FILE_ variable is present and you omit _FILE_=
in a particular FILE statement, then SAS creates an internal _FILE_= variable
for that FILE statement. Otherwise, SAS does not create the _FILE_= variable
for a particular FILE.
During execution and at the point of reference, the
maximum length of this character variable is the maximum length of the current
_FILE_= variable. However, because _FILE_ merely references other variables
whose lengths are not known until prior to the execution phase, the designated
length is 32,767 during the compilation phase. For example, if you assign
_FILE_ to a new variable whose length is undefined, the default length of
the new variable is 32,767. You can not use the LENGTH statement and the ATTRIB
statement to set or override the length of _FILE_. You can use the FORMAT
statement and the ATTRIB statement to assign a format to _FILE_.
Like other SAS variables, you can update the _FILE_
variable. The two methods are
-
_FILE_ = < 'quoted string'| character
expression>
-
This assignment statement updates the contents
of the current output buffer and sets the buffer length to the length of 'quoted string' or character expression.
However, this does not affect the PUT statement's current column pointer.
The next PUT statement for this FILE statement will begin to update the buffer
at column 1 or at the last known location when trailing @ is used in the PUT
statement. For example,
file print;
_file_='_FILE_';
put 'This is PUT';
outputs
This is PUT while
file print;
_file_='This is from FILE, oh yeah';
put @14 'both';
outputs
This is from both, oh yeah.
-
a PUT statement
-
The PUT statement will update the _FILE_
variable because the PUT statement formats data in the output buffer and _FILE_
points to that buffer. However, by default SAS clears the output buffers after
a PUT statement executes and outputs the current record (or N= block of records).
Therefore, if you wish to examine or further modify the contents of _FILE_
before it is output include a trailing @ or @@ in any PUT statement (when
N=1). For other values of N=, use a trailing @ or @@ in any PUT statement
where the last line pointer location is on the last record of the record block
. In the following code when N=1
file ABC;
put 'Something' @;
Y=trim(_file_)||' is here';
file ABC;
put 'Nothing' ;
y=trim(_file_)||' is here';
put y;
Y is first assigned
Something is here then Y is assigned
is here.
Any modification of the _FILE_ directly modifies the current
output buffer for the current FILE statement. The execution of any subsequent
PUT statements for this FILE statement will output the contents of the modified
buffer.
_FILE_ only accesses the contents of the current output
buffer for a FILE statement, even when you use the N= option to specify multiple
buffers. You can access all the N= buffers, but you must use a PUT statement
with the # line pointer control to make the desired buffer the current output
buffer.
This DATA step illustrates how to use the HEADER= option:
This DATA step demonstrates using the LINESLEFT= option
to determine where the page break should occur, according to the number of
lines left on the current page.
This example shows use of N=PAGESIZE in a DATA step
to produce a two-column telephone book listing, each column containing a name
and a phone number:
This DATA step causes a file identification message
to print in the log and assigns the value of the current output file to the
variable MYOUT. The PUT statement, demonstrating the assignment of the proper
value to MYOUT, writes the value of that variable to the output file:
data _null_;
length myout $ 200;
file file-specification filename=myout;
put myout=;
stop;
run;
The PUT statement writes a line to the current output
file that contains the physical name of the file:
MYOUT=your-output-file
This DATA step uses the FILEVAR= option to dynamically
change the currently opened output file to a new physical file.
Because the combined lengths of the variables are longer
than the output line (80 characters), this PUT statement automatically writes
three separate records:
file file-specification linesize=80;
put name $ 1-50 city $ 71-90 state $ 91-104;
The value of NAME appears in the first record, CITY
begins in the first column of the second record, and STATE in the first column
of the third record.
This example shows reading raw data from a file through
a TCP/IP socket. The NBYTE= option is used in the INFILE statement:
/* Start this first as the server */
filename serve socket ':5205' server
recfm=s
lrecl=25 blocksize=2500;
data _null_;
nb=25;
infile serve nbyte=nb;
input text $char25.;
put _all_;
run;
This example shows writing text to a file through a
TCP/IP socket:
/* While the server test is running,*/
/*continue with this as the client. */
filename client socket "&hstname:5205"
recfm=s
lrecl=25 blocksize=2500;
data _null_;
file client;
put 'Some text to length 25...';
run;
Copyright © 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.