Writing to External Files :: SAS(R) 9.3 Companion for z/OS, Second Edition

Overview of Writing to External Files

After allocating an external file, you can use the FILE statement, FILE command, or FOPEN function to write to the file. This section describes the FILE statement.

Note: You can also use FOPEN, FWRITE, FPUT, FNOTE, FPOINT, and FCLOSE to access external files. For more information, see SAS Functions and CALL Routines: Reference.

FILE Statement

About the FILE Statement

The FILE statement specifies the current output file for PUT statements in the DATA step. For a complete description of the PUT statement, see SAS Statements: Reference.

When multiple FILE statements are present, the PUT statement builds and writes output lines to the file that was specified in the most recent FILE statement. If no FILE statement was specified, the PUT statement writes to the SAS log.

The specified output file must be an external file, not a SAS library, and it must be a valid access type.

The FILE statement is executable. Therefore, you can use it in conditional processing (in an IF/THEN statement, for example).

As with INFILE, it is possible to alternately access multiple external files. See the example in Reading from Multiple External Files. You cannot write to multiple members of a single PDS at the same time. However, you can write to multiple members of a PDSE at one time.

Under z/OS, SAS uses the IBM ENQUEUE/DEQUEUE facility to prevent multiple users from writing to the same physical file simultaneously. This facility also prevents SAS software and ISPF from overwriting each other.

FILE Statement Syntax

This section provides a brief overview of FILE statement syntax. For complete information about the FILE statement, see FILE Statement: z/OS.

The syntax of the FILE statement is

FILE file-specification <type> <options > <host-options>;

file-specification

identifies the file. It can be in the following forms:

File Specification Examples for the FILE Statement

Form	Example
fileref	`report`
fileref(member)	`report(feb)`
'physical-filename'	`'library.daily.report'`
'physical-filename(member)'	`'library.daily.output(report1)'`
reserved filerefs	`LOG` or `PRINT`
HFS file	`'/u/userid/file'` `'HFS:myfile'`

See Specifying Physical Files for details about different ways of specifying physical-filename.

type

specifies the type of file. Nonstandard (host-specific) file types that you can specify for z/OS are

DLI

for IMS databases (see Accessing IMS and CA-IDMS Databases).

HFS and PIPE

for files in UNIX System Services (see Accessing UNIX System Services Files).

MVS

for z/OS data sets.

VSAM

for VSAM files (see Accessing VSAM Data Sets).

options

describe the output file's characteristics and specify how it is to be written with a PUT statement. Many of these options are not host-dependent and are documented in SAS System Options: Reference. For information about options that are specific to z/OS, see FILE Statement: z/OS. You can use these options to do the following:

define variables that contain information about the external file
specify special open and close processing
specify file characteristics

FILE Statement Examples

The following table contains examples of the FILE statement for different types of data sets.

Examples of the FILE Statement

Type of Data Set		Example
sequential		file 'my.new.dataset';
member of a PDS or PDSE		file out(newdata); or file 'my.new.dataset(newdata)';
sequential or member of a PDS or PDSE1		file myfilerf;
HFS		file '/usr/tmp/newdata';
HFS		file 'newmem.dat' hfs;
HFS		file 'HFS:raw';
MVS		file 'newmem.dat' mvs;
MVS		file 'MVS:raw';
VSAM		file payroll vsam;
IMS		file psb dli;
SAS log		file log;
1The type depends on what the fileref is associated with.

Writing to Sequential Data Sets

The disposition of a sequential data set can be OLD, MOD, or SHR. Using OLD eliminates the possibility of another job writing to the data set at the same time as your job is writing to it.

If you specify OLD or SHR, SAS begins writing at the beginning of the data set, replacing existing information. To append new information to the existing information, specify the MOD option in the FILE statement.

The following example assigns the fileref RAW to the data set MYID.RAW.DATAX and uses the fileref in a simple DATA step:

filename raw 'myid.raw.datax' disp=old;
data _null_;
   file raw;
   msgline='write this line';
   put msgline;
run;

Writing to Members of PDS or PDSE Data Sets

To write to a member of a PDS, include the following information:

the member name along with the data set name in the FILE statement
the FILENAME statement
the FILENAME function
the TSO ALLOCATE command or the JCL DD statement.

Omitting the member name causes an error message because SAS tries to treat the PDS as a sequential data set.

The disposition of the PDS member can be OLD or SHR; you cannot use a disposition of MOD for a member of a PDS. In both cases, SAS begins writing at the beginning of the member, replacing existing information. Using OLD eliminates the possibility of another job writing into the member at the same time as your job is writing into it.

You can write to only one member of a particular PDS in a single DATA step. However, you can write to members of separate PDSs. To write to more than one member of a given PDS, you must use a separate DATA step for each member. In a single DATA step, you can write to multiple members of a PDSE.

The following example assigns the fileref RAW to the PDS member MEM1 and then uses the fileref in a simple DATA step:

/* PDS Example */
filename raw 'myid.raw.data(mem1)' disp=old;
data _null_;
   file raw;
   put 'write this line';
run;

This next example assigns the fileref MYPDSE to the PDSE and then uses the fileref in a simple DATA step:

/* PDSE Example */
filename mypdse 'sales.div1.reg3' disp=shr;
data a;
   x=1;
   file mypdse(june97);
   put x;
   file mypdse(jul97);
   put x;
run;

Writing to a Printer

This example uses the FILENAME and FILE statements to route output to a printer:

filename prnt printer sysout=a;
data _null_;
   file prnt;
   put 'text to write';
run;

Writing to the Internal Reader

This example uses the FILENAME and FILE statements to write to an internal reader:

filename injcl '.misc.jcl' disp=shr;
filename outrdr sysout=a pgm=intrdr
      recfm=fb lrecl=80;
data _null_;
  infile injcl(myjcl);
  file outrdr noprint notitles;
  input;
  put _infile_;
run;

Writing to a Temporary Data Set

The following examples use the FILENAME and FILE statements to write to a temporary data set.

This example shows how to use default attributes to define a temporary file:
```
filename tempfile '&mytemp' ;
data out;
   file tempfile;
   put ...;
run;
```
The next example defines a temporary file and specifies some of its attributes:
```
filename nextone '&mytemp' disp=new
   lrecl=80 blksize=320 space=(trk,(3));
data out;
   file nextone;
   put ...;
run;
```
For information about specifying a temporary data set, see FILETEMPDIR System Option: z/OS.

Using the FILE Statement to Specify Data Set Attributes

You can specify data set attributes in the FILE statement as well as in the FILENAME statement or FILENAME function. SAS supplies default values for any attributes that you do not specify. For information about default values, see Overview of DCB Attributes and DCB Option Descriptions.

This example specifies values for LRECL= and RECFM= in the FILE statement and allows SAS to use the default value for BLKSIZE=:

filename x 'userid.newdata' disp=new
       space=(trk,(5,1)) volume=xyz111;
data out;
   file x lrecl=80 recfm=fb;
   put ... ;
run;

Using the Data Set Attributes of an Input File

In this example, data is read from the input file. Then the data is written to an output file, using the same file characteristics. The DCB option in the FILE statement tells SAS to use the same data set attributes for the output file as were used for the input file.

filename in  'userid.input';
filename out 'userid.output';
data;
   infile in;
   input;
   file out dcb=in;
   put _infile_;
run;

Using the FILE Statement to Specify Data Set Disposition

Appending Data with the MOD Option

In this example, the MOD option is used to append data to the end of an external file:

filename out 'user.output';
data _null_;
 /* New data is written to 'user.output'  */
   file out;
   put ... ;
run;

data _null_;
 /* data is appended to 'user.output'     */
   file out mod;
   put ... ;
run;

Appending Data with the MOD Disposition

This example is similar to the previous one except that instead of using the MOD option, the DISP= option is used. The OLD option is then used to overwrite the data.

filename out 'user.output' disp=mod;
data _null_;
 /* data is appended to 'user.output'    */
   file out;
   put ... ;
run;

data _null_;
 /* data is written at the beginning of  */
 /* 'user.output'                         */
   file out old;
   put ... ;
run;

data _null_;
 /* data is written at the beginning of  */
 /* 'user.output'                         */
   file out;
   put ... ;
run;

data _null_;
 /* data is appended to 'user.output'    */
   file out mod;
   put ... ;
run;

Writing to Print Data Sets

Overview of Print Data Sets

A print data set contains carriage-control information (also called ASA control characters) in column 1 of each line. These characters (blank, 0, −, +, and 1) control the operation of a printer, causing it to skip lines, to begin a new page, and so on. They do not normally appear on a printout. A nonprint data set does not contain any carriage-control characters.

When you write to a print data set, SAS shifts all column specifications in the PUT statement one column to the right to accommodate the carriage-control characters in column 1. Therefore, if you expect to print an external file, you should designate the file as a print data set either when you allocate it or when you write to it.

Designating a Print Data Set

The preferred method for designating a data set as a print data set is when you allocate it with one of the following methods:

the RECFM= option in the FILENAME statement
the FILENAME function
the JCL DD statement
the TSO ALLOCATE command.

Adding the letter A to the end of the value for the RECFM= option (RECFM=FBA or RECFM=VBA, for example) causes SAS to include carriage-control characters in the data set that is being created. For information about the RECFM= option, see FILENAME Statement: z/OS.

Designating a Nonprint Data Set as a Print Data Set

When you write to a data set that was not designated as a print data set when it was allocated, you can designate it as a print data set in several ways. The method that you use to designate it as a print data set depends on what you plan to do with the data set. Here are some examples:

Use the PRINT option in the FILE statement:
```
file saveit print;
```
SAVEIT is the fileref of the data set. The PRINT type in the FILE statement includes a page number, date, and title; this method is the simplest way to create a print data set.
Use PRINT as the fileref in the FILE statement (different from the PRINT option above):
```
file print;
```
The PRINT fileref in the FILE statement causes SAS to write the information either to the standard SAS procedure output file (PRINT=SASLIST), or to another output file if you have used a PROC PRINTTO statement to redirect your output. For information about PROC PRINTTO, see PRINTTO Procedure: z/OS and Using the PRINTTO Procedure and the FORM Subsystem. In either case, this file contains carriage-control characters by default. You can suppress the carriage-control characters by specifying the NOPRINT option in the FILE statement. For more information, see Writing to External Files.
Use the letter A as part of the value in the RECFM= option in the FILE statement:
```
file saveit recfm=vba;
```
As in the FILENAME statement or FILENAME function, the letter A in the RECFM= option of the SAS FILE statement causes SAS to include carriage-control characters in the data set that is being created. SAS also changes the record format of the target data set.

For information about how to process print files as input, see Reading from Print Data Sets.

Designating a Print Data Set as a Nonprint Data Set

The NOPRINT option is useful when you use a DATA step to copy a data set that already contains carriage-control information. In this case, use NOPRINT to prevent SAS from adding an additional column of carriage-control information.

If a data set has been allocated as a print data set, you can use the NOPRINT option in the FILE statement to omit carriage-control information. For example, suppose you specified RECFM=VBA, indicating a print data set, when you allocated a file and that you assigned the fileref OUTDD. The following SAS statement designates OUTDD as a nonprint data set:

file outdd noprint;

To write lines without carriage-control information to the SAS procedure output file, specify:

file print noprint;