Chapter Contents
Previous
Next
|
Chapter Contents |
Previous |
Next |
| FILENAME |
| Language element: | statement |
| Valid: | anywhere in a SAS program |
| OpenVMS specifics: | valid values for device-type; valid values for external-file; valid values for host-option-list |
Syntax |
FILENAME fileref
<device-type>
|
FILENAME fileref device-type
<'external-file'>
|
Note: This is a simplified version of the FILENAME statement syntax. For the
complete
syntax and its explanation, see the FILENAME statement in SAS Language Reference:
Dictionary. ![[cautionend]](../common/images/cautend.gif)
The following are some examples of valid filerefs:
The following are some examples of invalid filerefs:
Under OpenVMS, you can specify concatenations of files when reading and writing external files from within the SAS System. Concatenated files consist of two or more file specifications, enclosed in quotation marks and separated by commas. The following is an example of a valid concatenation specification:
filename alldata 'test.data1, test.data2,
test.data3';
For a complete discussion, see Using OpenVMS Pathnames to Identify External Files
For Version 8, if you specify a
version number for the file in a FILENAME
statement, the version number of the file is not increased. For example, the
following FILENAME statement will produce only one file,
test.dat;1:
filename myfile 'test.dat;1'; data; file myfile; put 'hello'; run; data; file myfile; put 'hello again'; run;
For more details, see Using OpenVMS Pathnames to Identify External Files. For more information about valid OpenVMS pathnames, refer to OpenVMS User's Manual.
| ALQ= | KEYVALUE= | NEW |
| CC= | LINESIZE= | OLD |
| DEQ= | LRECL= | PAGESIZE= |
| FAC= | MBC= | RECFM= |
| GSFCC= | MBF= | SHR= |
| KEY= | MOD |
These options control how the external file is processed and are specific to the OpenVMS environment. For information about these options, see Host-Specific External I/O Statement Options.
Many of the DCL print qualifiers are also supported as host options in the FILENAME and FILE statements. For details, see Printer Options in the FILENAME and FILE Statements.
Note: When using the PIPE device, only
the LRECL= host option is supported.
| Details |
The FILENAME statement is significantly different from the LIBNAME statement. The FILENAME statement is for external files only and references a specific filename. The LIBNAME statement is for SAS files only, and it generally specifies directory- and subdirectory-level information only (except when you are assigning a libref for use with the XPORT, OSIRIS, or SPSS engines). Also, unlike a libref, you can associate a fileref with a file that does not yet exist; when you use the fileref in a FILE statement or command, the file is created according to your specifications.
You can choose to use only a directory name in the FILENAME statement (the directory must exist, except when doing a concatenation). You must then use the fileref and the filename in subsequent statements as discussed in Using Aggregate Syntax to Identify External Files. The SAS System supplies a default file type.
| Reserved Filerefs |
| Device-Type Keywords |
filename myfile printer; data test; file myfile; put 'This is spooled to a printer.'; run;
The following are the valid device-type keywords and their meanings:
If you want to display and enter data in the same step, then issue two FILENAME statements and use one fileref for input and one for output.
For every record, the 2-byte control field is set to NULL, indicating no carriage control.
These keywords are valid only in the FILENAME statement. However, a fileref for which you specified a device-type keyword can be used in the SAS windowing environment commands and in the FILE, INFILE, and %INCLUDE statements. In order to use these devices correctly, you must specify the device-type keyword in the FILENAME statement. (If you use a device specification only in the quoted file specification of a FILE or INFILE statement, the results are unpredictable.) For example, to correctly send output to the display, use the following statements:
filename myfile terminal; data test; file myfile; put 'This is my test'; run;
By contrast, the following lines are incorrect and may yield unpredictable results:
data test2; file 'sys$output'; put 'This may not work in all cases.'; run;
When you use the TERMINAL device type with the INFILE statement, you terminate input by pressing CTRL-Z.
| Host-Specific External I/O Statement Options |
This list includes only options that are specific to the OpenVMS environment. For a complete list of external I/O statement options, see Summary of External I/O Statement Options and the statements chapter in SAS Language Reference: Dictionary.
The following descriptions include an explanation of the option, its valid and default values, and whether it is used for input, output, or both.
If the same option is used in both the FILENAME and FILE statements or in both the FILENAME and INFILE statements, the FILE or INFILE value takes precedence over the value used in the FILENAME statement.
The ALQ= option (allocation quantity) is used for output and corresponds to the FAB$L_ALQ field in OpenVMS Record Management Services (RMS). For additional details, refer to Guide to OpenVMS File Applications.
Only SAS print files are affected by the CC= option. The CC= option is used for output.
The CC= option also exists as a SAS system option (see CC=). If you specify this option both as a system option and in the FILENAME or FILE statement, then SAS uses the value that you specified in the FILENAME or FILE statement.
The DEQ= option (default file extension quantity) is used for output and corresponds to the FAB$W_DEQ field in OpenVMS RMS. For additional details, see Guide to OpenVMS File Applications.
FAC=access-option-listwhere access-option-list can be one of the following:
| DEL | specifies delete access. |
| GET | specifies read access. |
| PUT | specifies write access. |
| UPD | specifies update access. |
You can combine these values in any order. For example, specifying the following indicates you want delete, read, and write access:
fac=(del,get,put)
By also specifying the SHR= option, you can allow other users concurrent access to an external file, either through a separate SAS session or with another application. To allow sharing, you must include the values for FAC= in the list of values for SHR= (but the reverse is not true). For more information, see the description of the SHR= option later in this section.
The FAC= option (file access) can be used for both input and output and corresponds to the FAB$B_FAC field in OpenVMS RMS or the ACCESS attribute when using File Definition Language (FDL). For additional details on file sharing, see Guide to OpenVMS File Applications.
| creates a GSF file. It is a VFC format file with carriage control set to null. These files can be used with most utilities with the exception of some file transfer protocols, such as Kermit. This is the default value for this option. | |
| CR | creates a carriage return carriage control file. |
| NONE | creates a file with no carriage control. This format is useful if you plan to download the file to a personal computer. |
This option also exists as a SAS system option (see LINESIZE=). If this option is used both as a system option and in the INFILE or FILE statement, the SAS System uses the value given in the INFILE or FILE statement.
The maximum record size for OpenVMS is 32,767. LRECL values greater than 32,767 are valid only when reading and writing to tape. If an LRECL value greater than 32,767 is specified when writing to a non-tape device, the LRECL value is set 32,767. You should use the maximum LRECL values for the various file types provided in Maximum LRECL Values for File Types.
Because the FLOWOVER option on the FILE statement is the default, lines that are longer than the length specified by the LRECL= option are split.
When accessing unlabeled tapes, you must use LRECL=. The minimum value in this case is 14. For more information, see Reading from an Unlabeled Tape.
The LRECL= option is used for both input and output.
| File Organization | Record Format | Maximum LRECL Value |
|---|---|---|
| Sequential | Fixed length | 32,767 |
| Sequential (disk) | Variable length | 32,765 |
| Sequential (disk) | VFC | 32,767-FSZ |
| Sequential (disk) | Stream | 32,767 |
| Sequential (disk) | Stream-CR | 32,767 |
| Sequential (disk) | Stream-LF | 32,767 |
| Sequential (ANSI Tape) | Variable length | 9,995 |
| Sequential (ANSI Tape) | VFC | 9,995-FSZ |
| Relative | Fixed length | 32,255 |
| Relative | Variable length | 32,253 |
| Relative | VFC | 32,253-FSZ |
| Indexed, Prolog 1 or 2 | Fixed length | 32,234 |
| Indexed, Prolog 1 or 2 | Variable length | 32,232 |
| Indexed, Prolog 3 | Fixed length | 32,224 |
| Indexed, Prolog 3 | Variable length | 32,224 |
FSZ represents the size, in bytes, of the fixed control area in a record with VFC record format.
The MBC= option (multiblock count) is used for both input and output to control the allocation for a particular file. If you want to control the allocation size for all the external files used during the current SAS session, you can use the MBC= option in every FILE, FILENAME, or INFILE statement. You can also use the DCL SET RMS_DEFAULT command to specify a process default, and let the SAS System value default to the process's default values.
The MBC= option corresponds to the RAB$B_MBC field in OpenVMS RMS or the CONNECT MULTIBLOCK_COUNT attribute when using FDL. This option is not supported for DECnet operations. For additional details, see Guide to OpenVMS File Applications.
The MBF= option (multibuffer count) is used for both input and output to control the number of buffers allocated for a particular file. If you want to control the number of buffers allocated for all the external files used during the SAS session, you can use the MBF= option in every FILE, FILENAME, or INFILE statement. The DCL SET RMS_DEFAULT command can be used to specify a process default. Then, you can let the SAS System value default to the process's default values.
The MBF= option corresponds to the RAB$B_MBF field in OpenVMS RMS or the CONNECT MULTIBUFFER_COUNT attribute when using FDL. This option is not supported for DECnet operations. For additional details, see Guide to OpenVMS File Applications.
This option also exists as a SAS system option (see PAGESIZE=). If this option is used both as a system option and in the FILE statement, the SAS System uses the value given in the FILE statement.
| F | specifies fixed length. |
| V | specifies variable length. |
| D | specifies you are accessing unlabeled tapes with the PUT and INPUT DATA step statements. For more information, see Reading from an Unlabeled Tape. |
If the RECFM= option is not used, the value defaults to V for output files. For input files, the default value is the record format of the file.
This option is used for both input and output.
However, you can allow other users to have read and write access to a file that you are opening for input only. To accomplish this, use the SHR= option. The syntax of the SHR= option is
SHR=share-option-listwhere share-option-list can be one of the following:
| DEL | specifies delete access. |
| GET | specifies shared read access. |
| NONE | specifies no shared access. |
| PUT | specifies shared write access. |
| UPD | specifies update access. |
You can combine these values in any order. For example, specifying the following indicates you want shared delete, read, and write access:
shr=(del,get,put)
To allow shared access, the values for FAC= must be included in the list of values for SHR= (but the reverse is not true).
This option corresponds to the FAB$B_SHR field in OpenVMS RMS or the SHARING attribute when using FDL. For more information about file sharing, see Guide to OpenVMS File Applications.
The SHR= option is used for both input and output.
Note: When using the PIPE device, only the LRECL= host option is
supported.
| Using the KEY= Option |
The key number is zero-based, so KEY=0 (the default) specifies that the records be read in sorted order by the primary key. KEY=1 specifies the use of the first secondary key to access the records.
/*-------------------------------------------*/
/* This SAS program accesses an empty */
/* indexed file that has been previously */
/* created. The data are appended to the */
/* file. Primary key #0 is of type character */
/* and is in bytes 0-2. Secondary key #1 is */
/* of type character and is in bytes 3-5. */
/*-------------------------------------------*/
filename myfile 'indexed.dat';
/* Load the indexed file, primary key in */
/* sorted order. */
data _null_;
file myfile mod;
put 'aaaccc';
put 'bbbaaa';
run;
/* Print out in primary key sorted order. */
data _null_;
/* Key=0 is the default. */
infile myfile;
input first $3. second $3.;
put first= second=;
run;
This program produces the following output:
first=aaa second=ccc first=bbb second=aaa
In contrast, consider setting KEY=1 as in the following example:
/* Print out in secondary key sorted order. */ data _null_; infile myfile key=1; input first $3. second $3.; put first= second=; run;
This program produces the following output:
first=bbb second=aaa first=aaa second=ccc
All keys are defined in RMS when the file is created. For more information about defining and using keys in an indexed file, see Guide to OpenVMS File Applications.
| Using the KEYVALUE= Option |
Valid forms of the KEYVALUE= option are
KEYVALUE operator value AND KEYVALUE operator value KEYVALUE=SAS-variable
| < | less than |
| <= | less than or equal to |
| > | greater than |
| >= | greater than or equal to. |
The key specified in the KEY= option is used with the KEYVALUE= option. The defined order of the key specified must match the direction of the operator given in the KEYVALUE= option. For example, if the key is an ascending order key, the < and <= operators are invalid operators. When the value of KEYVALUE= is a constant value, the file is processed sequentially by key, beginning with the given value. When the value of KEYVALUE= is a SAS variable, the first record with a key satisfying the criterion of the KEYVALUE expression is read from the file. Note that the SAS variable value must match the key value of one of the records exactly or an end-of-file condition occurs.
The data type of the key specified in the KEY= option must also correspond to the type given as the value for the KEYVALUE= option. The following RMS data types are supported by the KEYVALUE= option:
The SAS System converts an integer value to the correct format of the supported numeric types. Character string values are not changed when used for the character type.
When you use date-time values, the data are stored in signed 8-byte binary RMS key fields. Use the VMSTIMEF. format to convert SAS date-time values to signed 8-byte binary values. When you access records through a date-time value key using the KEYVALUE=SAS-variable option, the SAS variable must have one of the following SAS formats or informats associated with it:
| DATEw. | |
| DATETIMEw. | |
| DDMMYYw. | |
| JULIANw. | |
| MMDDYYw. | |
| MONYYw. | |
| YYMMDDw. | |
| YYQw. |
A format or informat must be associated with the SAS variable because neither the variable value nor the field value within the record indicates that the data represent date-time values. For more information about these formats and informats, refer to SAS Language Reference: Dictionary.
Suppose you want to input an indexed file that has an alternate key defined as a signed 4-byte integer in descending sort order. You can process only the records with the values less than 5,000 with the following DATA step:
filename in 'indexed.dat' key=2 keyvalue<5000; data _null_; infile in; input name $9. num; put name num; run;
filename in 'indexed.dat' keyvalue>=-10 and keyvalue<=10;
When given a compound KEYVALUE expression, the SAS System reads records from the input file until a record is read with a key exceeding the upper boundary, which is 10 in this example, or until the end of file is reached. Note that the AND construct has an associative property; the order of the KEYVALUE options can be reversed and the meaning preserved. However, the operators still must match the key sort order, so the following DATA step using the same indexed file described in the earlier example generates an error:
data wrong;
infile 'indexed.dat' keyvalue<=-10 and
keyvalue>=10;
input num name $9.;
put name num;
run;
This DATA step generates the following error and warning messages:
ERROR: Specified key on indexed file is
defined as ascending but <, <= or
= was used in KEYVALUE option.
NOTE: The SAS System stopped processing
this step because of errors.
WARNING: The data set WORK.WRONG may be
incomplete. When this step was
stopped there were O observations
and 1 variables.
For example, suppose you have a SAS data set named SALES that has three variables: SALESREP, ITEMNO, and QUANTITY. This data set contains the number of items each salesperson sold during the last month. You also have an indexed file keyed by the item numbers of the products the company sells. Stored in each record is the price of the item. Using these two files, the SAS System can easily generate a report of the revenue generated by each salesperson:
filename parts 'inventory.idx' key=0;
filename report 'revenue.lis';
data revenue;
set sales;
infile parts keyvalue=itemno;
input itemno price;
revenue=quantity*price;
output @5 salesrep @30 itemno
@50 revenue dollar3.2;
stop;
run;
This sample program match-merges the observations in SALES with the records in the indexed file by item number to produce the reports. A KEYVALUE= option with a SAS variable name can be used only with the equal sign (=) operator and cannot be used in compound KEYVALUE expressions.
Note that in the previous example, the DATA step is driven entirely by the SET statement. The DATA step terminates when all records from the data set SALES have been processed. It is possible to use the SAS variable form of the KEYVALUE= option with other types of control mechanisms. In the following example, an iterative DO loop determines the set of records read from an indexed file:
data example2;
do i=1 to 20 by 2;
infile myfile key=0 keyvalue=i;
input var1 var2 var3 ...;
/* .... variable processing ... */
output var1 var2 var3 ...;
end;
stop;
run;
In this example, the DO loop is used to read every other record from MYFILE. Note that the STOP statement terminates the DATA step and closes the input file. Because the KEYVALUE=I option reads only those records specified in the DO statement, the SAS System cannot read an end-of-file indicator as it would if it were reading the file sequentially. Without the STOP statement to end the DATA step, the SAS System can get into an infinite loop by accessing the same index file repeatedly.
For more information about indexed files and keys, refer to Guide to OpenVMS File Applications.
| Summary of External I/O Statement Options |
| Option | Use | Option | Use |
|---|---|---|---|
| ALQ= ** | output | LINESIZE= * | input, output |
| CC= ** | output | LRECL= * | input, output |
| COLUMN= *** | input, output | MBC= ** | input, output |
| DELIMITER= *** | input | MBF= ** | input, output |
| DEQ= ** | output | MISSOVER *** | input |
| DROPOVER *** | output | MOD * | output |
| END= *** | input | N= *** | input, output |
| EOF= *** | input | NEW ** | output |
| EXPANDTABS *** | input | NOTITLES *** | output |
| FAC= ** | input, output | OBS= *** | input |
| FILENAME= *** | input, output | OLD * | output |
| FILEVAR *** | input, output | PAD *** | input, output |
| FIRSTOBS= *** | input | PAGESIZE= * | output |
| FLOWOVER *** | input, output | PRINT *** | input, output |
| GSFCC ** | output | RECFM= * | input, output |
| HEADER= *** | output | SHR= ** | input, output |
| KEY= ** | input | SHAREBUFFERS *** | input |
| KEYVALUE= ** | input | START= *** | input |
| LENGTH= *** | input | STOPOVER *** | input, output |
| LINE= *** | output | UNBUFFERED *** | input |
| *This option is also documented in SAS Language Reference:
Dictionary.
**All the information for this option is contained in this document. ***This option is completely documented in SAS Language Reference: Dictionary. |
|||
| Printer Options in the FILENAME and FILE Statements |
A complete list of supported options follows. For more information about the meanings of specific options, refer to OpenVMS DCL Dictionary.
| Examples |
filename pgmsas '[yourdir]prog1.sas'; %include pgmsas;
Consider the following FILENAME statement:
filename myfile '[mydir]';
If you want to use a file in [MYDIR] named SCORES02.DAT as input to an INFILE statement, issue the following statement:
infile myfile(scores02);
The SAS System assumes a file type of .DAT in the INFILE statement.
If you do not specify a file type in the external file specification, the default file type is .DAT. For example, the following FILENAME statement associates the fileref MYFILE with a file named SURVEY.DAT:
filename myfile 'survey';
The following statement sends a copy of the file A.LIS to the CLXYJ31 queue, holds it until 2:00 p.m., and then prints two copies:
filename x printer 'a.lis' queue=clxyj31
after="14:00:00" copies=2;
The following statement creates the file A.LIS but does not send it to the printer because the PRINTER device-type keyword is not used. The AFTER= option is ignored.
filename x 'a.lis' after="14:00:00";
The following statement sends the file A.LIS to the SYS$PRINT queue, holding it until 2:30 p.m.:
filename x printer 'a.lis' after="14:30:00";
The following statement creates a temporary file called SAS0000n and sends it to the SYS$PRINT queue. The file is deleted after printing.
filename x printer;
The following statement creates the file CLXYJ31.DAT and sends it to the SYS$PRINT queue. The file is not deleted after printing.
filename x printer 'clxyj31';
As a final example, the following lines create a file A.LIS and send it to the SYS$PRINT queue. The job name submitted is MYFILE.
filename x printer 'a.lis'; data a; file x name="myfile"; . . . more SAS statements . . . run;
| See Also |
|
Chapter Contents |
Previous |
Next |
 Top of Page |
Copyright 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.