|Statements under OpenVMS|
|Valid:||anywhere in a SAS program|
|OpenVMS specifics:||valid values for device-type, encoding-value, external-file, and host-option-list|
|See:||FILENAME Statement in SAS Language Reference: Dictionary|
|Host-Specific External I/O Statement Options|
|Using the KEY= Option|
|Using the KEYVALUE= Option|
|Using Compound Expressions|
|Using SAS Variables|
|Summary of External I/O Statement Options|
|Printer Options in the FILENAME and FILE Statements|
|Example 1: Associating a Fileref with an External File|
|Example 2: Using a File as Input to an INFILE Statement|
|Example 3: Using Printer Options|
FILENAME fileref <device-type>
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.
is any valid fileref and can be up to eight characters long. The first character must be a letter (A-Z), an underscore (_), a dollar sign ($), a pound sign (#), or an at sign (@). Subsequent characters can be any of these characters, or they can be numbers. Neither OpenVMS nor SAS distinguishes between uppercase and lowercase letters in filerefs or in filename specifications. This is a required argument. See Reading from and Writing to OpenVMS Commands (Pipes) for information about assigning a fileref to a pipe to read from and write to OpenVMS commands.
specifies an output device. For details about device types, see Device-Type Keywords. The device-type keyword must follow fileref and must precede external-file (if an external file is used).
can be any valid file specification. You must enclose the file specification in quotation marks. The file specification must be a valid OpenVMS pathname to the external file that you want to access. Therefore, the level of specification depends on your location in the directory structure. The number of characters in the quoted string must not exceed the maximum filename length that OpenVMS allows (255 characters).
Under OpenVMS, you can specify concatenations of files when reading and writing external files from within SAS. 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:
For a complete discussion, see Using OpenVMS Pathnames to Identify External Files
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, see OpenVMS User's Manual.
When you read data from an external file, SAS transcodes the data from the specified encoding to the session encoding. When you write data to an external file, SAS transcodes the data from the session encoding to the specified encoding.
For valid encoding values, see Encoding Values in SAS Language Elements in SAS National Language Support (NLS): Reference Guide.
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 you are using the PIPE device, only the LRECL= host option is supported.
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 based on your specifications.
You can choose to use only a directory name in the FILENAME statement (the directory must exist, except when you are 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. SAS supplies a default file type.
specifies that input data immediately follows a DATALINES statement in your SAS stream. The only time you need to use the INFILE DATALINES fileref is when you want to use INFILE statement options to read in stream data.
When you specify a device-type in a FILENAME statement, the external-file argument is optional. If you do specify an external file, its meaning depends on which device type you specified. For example, the following SAS program sends the output file to the printer that is associated with the SYS$PRINT queue:
references a SAS catalog as a flat file. The external file is a valid two-, three-, or four-part SAS catalog name followed by any catalog options needed. See SAS Language Reference: Dictionary for a description of catalog options.
sends the output to or reads the input from a disk device. This is the default behavior if you do not specify any device-type keywords in the FILENAME statement. You must specify an external file with this keyword.
sends the output to NLA0: (the null device). If you specify an external file, the file specification is ignored. This device-type keyword is useful when you are debugging SAS programs. You can test your algorithms without actually writing output files.
sends electronic mail to an address. The external file is an address and e-mail options. See Sending Electronic Mail Using the FILENAME Statement (E-MAIL) for more information.
reads or writes to a file from any machine on a network that is running an FTP server. The external file is the pathname of the external file on the remote machine followed by FTP options. See SAS Language Reference: Dictionary for more information.
sends the output to or reads the input from an OpenVMS command. For more information, see Reading from and Writing to OpenVMS Commands (Pipes).
Note: The PIPE device cannot be used from a captive account. For more information, see Limitations of Using a Captive Account.
spools the output to a printer queue that has been assigned to a plotter. This keyword works the same as the PRINTER keyword except that the file format is valid for a plotter device. The file that is created is an OpenVMS print file; it has a variable record format, with a 2-byte, fixed-length control field.
spools the output to a printer queue. If you do not specify an external file, the output is sent first to a temporary file on disk and then to the SYS$PRINT queue. Then the disk file is deleted. If you do specify a file, the output is sent to that file and then sent to the SYS$PRINT queue. In this case, the disk file is not deleted. To send the output to a printer queue other than SYS$PRINT, use the QUEUE= option in the FILENAME or FILE statement. For information about printer options, see Printer Options in the FILENAME and FILE Statements.
reads and writes information over a TCP/IP socket. The external file depends on whether the SAS application is a server application or a client application. In a client application, the external file is the name or IP address of the host and the TCP/IP port number to connect to followed by any TCP/IP options. In server applications, it is the port number to create for listening, followed by the SERVER keyword, and then any TCP/IP options. See SAS Language Reference: Dictionary for more information.
is a temporary file that can be accessed only through the logical name and is available only while the logical name exists. If a physical pathname is specified, an error is returned. Files manipulated by the TEMP device can have the same attributes and behave identically to DISK files.
sends the output to or reads the input from a terminal device. If you do not specify an external file, the output goes to the SYS$OUTPUT output stream. If you do specify an external file, the file specification is ignored and SYS$OUTPUT is still used.
enables you to access remote files using the URL of the file. The external file is the name of the file that you want to read from or write to on a URL server. The URL must be in one of the following forms:SAS Language Reference: Dictionary for more information.
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. 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:
|Host-Specific External I/O Statement Options|
The following external I/O statement options can be used in the FILE, INFILE, and FILENAME statements. Note that some of these options, such as ALQ=, have the same names as SAS data set options. Do not confuse the two types of options. You cannot use data set options with external files.
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 SAS statements documentation in SAS Language Reference: Dictionary.
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.
specifies the number of blocks initially allocated to an external file when it is created. The value can range from 0 to 2,147,483,647. If the value is 0 (the default), the minimum number of blocks required for the given file format is used.
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, see Guide to OpenVMS File Applications.
The CC= option also exists as a SAS system option (see CC= System Option: OpenVMS). 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.
specifies the number of blocks added when OpenVMS RMS automatically extends an external file during a write operation. The value can range from 0 to 65,535. The default value is 0, telling OpenVMS RMS to use the process's default value. A large value results in fewer file extensions over the life of the file; a small value results in numerous file extensions over the life of the file. A file with numerous file extensions might be noncontiguous, thereby slowing record access.
overrides the default file access attributes used for external files. Use this option to indicate the level of access you want to allow for an external file. You can allow READ, WRITE, UPDATE, and DELETE access (as well as no access). By default with external files, files opened for input allow read access, files opened for output allow WRITE access, and files opened for update allow READ and WRITE access. The form of the FAC= option isaccess-option-list can be one of the following:
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 about 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.
specifies which key SAS uses to read the records in an RMS file with indexed organization. The KEY= option is always used with the KEYVALUE= option. For details, see Using the KEY= Option and Using the KEYVALUE= Option.
specifies the key value with which to begin reading an indexed file. For details, see Using the KEYVALUE= Option.
specifies the record length of the output file. If you do not specify a record length, the default is the value of the LRECL= system option. For the input file, the existing record length is used by default. If the LRECL= option is used, the input records are padded or truncated to the specified length.
The maximum record size for OpenVMS is 32,767. However, your LRECL= value might differ depending on the record format you use. Use the maximum LRECL value for the various file types provided in the following table.
|File Organization||Record Format||Maximum LRECL Value|
|Sequential (disk)||Variable length||32,765|
|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|
Alternatively, you can specify a logical record length value by using the LRECL= system option.
specifies the size of the I/O buffers that OpenVMS RMS allocates for a particular file. The value can range from 0 to 127 and represents the number of blocks used for each buffer. By default, this option is set to 0 and the default values for the process are used.
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 values 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.
specifies the number of I/O buffers you want OpenVMS RMS to allocate for a particular file. The value can range from 0 to 127 and represents the number of buffers used. By default, this option is set to a value of 2. If a value of 0 is specified, the default value for the process is used.
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 values 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.
specifies binary format. The file consists of a stream of bytes with no record boundaries. N is not valid for the PIPE device type. If you do not specify the LRECL= host option or the LRECL= system option, then, by default, SAS reads 256 bytes at a time from the file.
specifies StreamLF record format. Records are delimited by LF.
overrides the default file-sharing attributes used for external files. With this option, you can indicate the access level you want to give other users. You can allow READ, WRITE, UPDATE, and DELETE access (as well as no access). By default with external files, files opened for input allow shared read access, and files opened for output or UPDATE do not allow shared access.share-option-list can be one of the following:
Note: When you are using the PIPE device, only the LRECL= host option or LRECL= system option is supported.
|Using the KEY= Option|
The KEY= option is used for input. It is always used with the KEYVALUE= option. A key is a record field that identifies the record and helps you retrieve it in an indexed file. The two types of keys are primary and alternate. Data records are stored in the file in the order of their primary key. Alternate keys (also called secondary keys) create alternate indexes in the file. The alternate index can then be used to process the records in order of the alternate key. The only difference between the primary key and the alternate key is that the records are actually stored in the order of the primary key, whereas the alternate key provides a means of accessing them.
To use SAS to write to an indexed file, you can either create an empty indexed file or use any existing indexed file. If you create an empty indexed file, use FDL to specify the file characteristics, including the type and location of primary and secondary keys. (For more information about FDL, see OpenVMS File Definition Language Facility Manual.) The following is an example program:
/*-------------------------------------------*/ /* This SAS program accesses an empty */ /* indexed file that has been previously */ /* created. The data is 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;
/* Print out in secondary key sorted order. */ data _null_; infile myfile key=1; input first $3. second $3.; put first= second=; run;
|Using the KEYVALUE= Option|
The KEYVALUE= option is always used with the KEY= option, which specifies the key used by SAS to read the records in an RMS file with indexed organization. When you use the KEYVALUE= option, the file is read sequentially, beginning with the value you specified. It is similar to the FIRSTOBS= option used with a sequential-format file. You can specify a SAS variable name with the KEYVALUE= option to drive random reads from the file. The KEYVALUE= option is used for input.
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.
When you use date-time values, the data is 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:
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 represents date-time values. For more information about these formats and informats, see 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;
You can further restrict the number of records read by using a compound KEYVALUE expression. For example, suppose you want to input an indexed file that has a primary key defined as a signed 2-byte integer in ascending sort order. You can retrieve records with key values between -10 and 10 inclusive with the following FILENAME statement:
When given a compound KEYVALUE expression, SAS 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;
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.
Using a SAS variable name as the value of the KEYVALUE= option enables you to randomly access records in the indexed file. In the previous examples of using the KEYVALUE= option, the input file was sequentially accessed. You can use any SAS variable with the KEYVALUE= option that matches the type of the key in question. When SAS reads from the file, it reads the first record with the key value that matches the value of the SAS variable.
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, SAS 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, SAS 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, SAS can get into an infinite loop by accessing the same index file repeatedly.
|Summary of External I/O Statement Options|
The following table alphabetically lists all available external I/O statement options, including both options that are valid in all operating environments and options that are specific to the OpenVMS environment. The Use column indicates whether the option is used for input, output, or both. The support of the options in the FILENAME statement is host-specific. Options that are used with the FILENAME statement are not documented in SAS Language Reference: Dictionary.
|ALQ= **||output||LINE= ***||output|
|CC= **||output||LINESIZE= *||input, output|
|COLUMN= ***||input, output||LINESLEFT= ***||output|
|DELIMITER= ***||input||LRECL= *||input, output|
|DEQ= **||output||MBC= **||input, output|
|DLMOPT=***||input, output||MBF= **||input, output|
|DLMSTR= ***||input, output||MISSOVER ***||input|
|DROPOVER ***||output||MOD *||output|
|DSD ***||input, output||N= ***||input, output|
|ENCODING=***||input, output||NEW **||output|
|END= ***||input||NOTITLES ***||output|
|EOF= ***||input||OBS= ***||input|
|EOV= ***||input||OLD *||output|
|EXPANDTABS ***||input||ODS ***||output|
|FAC= **||input, output||PAD ***||input, output|
|FILENAME= ***||input, output||PAGESIZE= *||output|
|FILEVAR ***||input, output||PRINT ***||input, output|
|FIRSTOBS= ***||input||RECFM= *||output|
|FLOWOVER ***||input, output||SHR= **||input, output|
|FOOTNOTES ***||output||SHAREBUFFERS ***||input|
|GSFCC= **||output||START= ***||input|
|HEADER= ***||output||STOPOVER ***||input, output|
|KEY= **||input||TRUNCOVER ***||input|
|KEYVALUE= **||input||UNBUFFERED ***||input|
|LENGTH= ***||input||_FILE_= ***||output|
|* This option is also documented in SAS Language Reference: Dictionary.|
|Printer Options in the FILENAME and FILE Statements|
Many of the DCL print qualifiers are supported as host options in the FILE and FILENAME statements. If the same option is used in both the FILE and FILENAME statements, the FILE statement value overrides the FILENAME statement value. You send a file to a printer by using the PRINTER or PLOTTER device-type keyword in the FILENAME statement.
sends a list of up to eight parameters to the printer device. The PARAM= value can be one item without parentheses, or a group of items enclosed by parentheses. If the value contains blanks or nonalphanumeric characters, enclose the entire value argument in single or double quotation marks.
specifies the name of the printer queue to send the job to. If this option is not used, the job is submitted to the SYS$PRINT queue. If the queue name contains characters not recognized by SAS, it must be enclosed in single quotation marks; for example, SYS$PRINT must be enclosed in quotation marks, but CLXYJ31 does not need to be. The queue-name argument cannot contain any spaces.
In this example, the FILENAME statement associates the fileref PGMSAS with an external file that contains a SAS program. PGMSAS is then used as the fileref in the %INCLUDE statement to read a file that contains SAS statements.
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: