Statements under OpenVMS

FILENAME Statement: OpenVMS

Associates a SAS fileref with an external file or output device.

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

Syntax
Details
Reserved Filerefs
Device-Type Keywords
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
Examples
	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
See Also

Syntax

FILENAME fileref <device-type>

'external-file' <ENCODING='encoding-value'><host-option-list>;

FILENAME fileref device-type <'external-file'><ENCODING='encoding-value'>

<host-option-list>;

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]

fileref

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.

The following are some examples of valid filerefs:

TEST_1
MYFILE
abc123

The following are some examples of invalid filerefs:

ALONGFILENAME (longer than eight characters)
123_test (begins with a number)
TEST%X (contains an invalid character (%)).

device-type

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).

'external-file'

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:

filename alldata 'test.data1, test.data2, test.data3';

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.

ENCODING='encoding-value'

specifies the encoding to use when reading from or writing to the external file. The value for ENCODING= indicates that the external file has a different encoding from the current session encoding.

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.

host-option-list

names any of the following external I/O statement options:

ALQ=	KEY=	MOD
CC=	KEYVALUE=	NEW
DEQ=	LRECL=	OLD
FAC=	MBC=	RECFM=
GSFCC=	MBF=	SHR=

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. [cautionend]

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 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.

Reserved Filerefs

Under OpenVMS, the following are reserved filerefs (the items in parentheses are the SAS statements to which each applies):

DATALINES (INFILE): 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.
LOG (FILE): specifies that output lines produced by PUT statements are written to the SAS log. LOG is the default destination for output lines.
PRINT (FILE): specifies that output lines produced by PUT statements are written to the procedure output file, the external file to which SAS procedure output is written.

Device-Type Keywords

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:

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:

CATALOG

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.

DISK

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.

DUMMY

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.

EMAIL

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.

FTP

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.

PIPE

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. [cautionend]

PLOTTER

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.

For every record, the 2-byte control field is set to NULL, indicating no carriage control.

PRINTER

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.

SOCKET

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.

TEMP

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.

TERMINAL

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.

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.

UPRINTER

sends output to the default printer that was set up through the Print dialog box.

URL

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:

http://hostname/file
http://hostname:portno/file

See 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:

filename myfile terminal;

data test;
   file myfile;
   put 'This is my test';
run;

By contrast, the following lines are incorrect and might 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

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.

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.

ALQ=

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.

BLKSIZE= | BLK=

is no longer supported in the OpenVMS operating environment.

CC=

specifies the carriage-control format of the SAS log and the procedure output file. This option has three possible values:

FORTRAN: indicates FORTRAN carriage-control format. This is the default for print files.
PRINT: indicates OpenVMS print format.
CR: indicates OpenVMS carriage-return, carriage-control format. This is the default for nonprinting files.

Only SAS procedure output 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= 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.

DEQ=

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.

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=

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 is

FAC=access-option-list

where 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 that 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 about file sharing, see Guide to OpenVMS File Applications.

GSFCC=

specifies the file format of graphic stream files (GSF files). When specified in the FILENAME statement, it affects only the GSF files that are created using that fileref. The accepted values are

PRINT	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.

KEY=

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.

KEYVALUE=

specifies the key value with which to begin reading an indexed file. For details, see Using the KEYVALUE= Option.

LRECL=

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.

Because the FLOWOVER option in the FILE statement is the default, lines that are longer than the length specified by the LRECL= option are split.

The LRECL= option is used for both input and output.

Maximum LRECL Values for File Types
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
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.

Alternatively, you can specify a logical record length value by using the LRECL= system option.

MBC=

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.

MBF=

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.

MOD

opens the file referenced for append. This option does not take a value. An existing file of the name given in the FILENAME or FILE statement is opened and new data is appended to the end.

NEW

opens a new file for output. This option does not take a value. This is the default action for files referenced by a FILE statement. Under OpenVMS, this option is synonymous with the OLD option.

OLD

opens a new file for output. This option does not take a value. This is the default action for files referenced by a FILE statement. Under OpenVMS, this option is synonymous with the NEW option.

RECFM=

specifies the record format of the output file. Values for the RECFM= option are as follows:

F	specifies fixed length.
N	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.
STREAMLF	specifies StreamLF record format. Records are delimited by LF.
V	specifies variable length.

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.

SHR=

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.

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-list

where 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 that 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 you use 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 you are using the PIPE device, only the LRECL= host option or LRECL= system option is supported. [cautionend]

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.

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.

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;

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

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.

Valid forms of the KEYVALUE= option are as follows:

KEYVALUE operator value
   AND KEYVALUE operator value

KEYVALUE=SAS-variable

where operator can be one of the following:

<	less than
<=	less than or equal to
>	greater than
>=	greater than or equal to.

where value can be one of the following data types:

integer
quoted string
quadword (signed or unsigned)
packed decimal
date/time

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:

unsigned 2-byte binary
unsigned 4-byte binary
unsigned 8-byte binary
signed 2-byte binary
signed 4-byte binary
signed 8-byte binary
left-justified string of characters
packed decimal string of characters

SAS 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 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:

	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 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;

Using Compound Expressions

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:

filename in 'indexed.dat' keyvalue>=-10 and
   keyvalue<=10;

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;

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.

Using SAS 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.

For more information about indexed files and keys, see Guide to OpenVMS File Applications.

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.

Summary of External I/O Statement Options
Option	Use	Option	Use
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
		_INFILE_= ***	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 either the FILE statement or the INFILE statement 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.

A complete list of supported options follows. For more information about the meanings of specific options, see OpenVMS DCL Dictionary.

AFTER="quoted-string": specifies a time after which the file can be printed. The time can be specified as absolute time or a combination of absolute and delta times and must be enclosed in double quotation marks.
BURST=ALL | NO: specifies a burst page or not. The default value is NO.
CHAR=(,,,): lists characteristics for the printer. The list can be one item or a group of items enclosed by parentheses. No spaces are allowed in the list.
COPIES=n: specifies the number of copies to print. The default value is 1.
FEED=YES | NO: specifies whether to perform a form feed at the end of the page. The default value is YES.
FLAG=ALL | NO: specifies whether to print a flag page preceding each file. The default value is NO.
FORM=type: defines the form name or number used.
HDR=YES | NO: controls whether a header line is printed at the top of each page. The default value is NO.
NAME=quoted-string: specifies the name of the submitted job shown when you issue a SHOW QUEUE command. The default is the filename. The quoted-string argument can contain spaces.
NOTE=quoted-string: specifies a message to appear on the flag page. The quoted-string argument can contain spaces.
NOTIFY=YES | NO: controls whether to notify the user when the job is finished. The default value is NO.
PARAM=<">(,,,)<">: 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.
PASSALL=YES | NO: specifies whether all formatting is bypassed and sent to the device driver with formatting suppressed. The default value is NO.
QUEUE=<">queue-name<">: 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.
RESTART=YES | NO: restarts the job after a crash. The default value is YES.
SETUP=(,,,): sets up module names to extract from the device control library. The list can be a single item or a group of items enclosed by parentheses.
SPACE=1 | 2: specifies double- or single-spacing. The default value is single.
TRAILER=ALL | NO: prints a trailer page at the end of the file. The default value is NO.

Examples

Example 1: Associating a Fileref with an External File

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.

filename pgmsas '[yourdir]prog1.sas';
%include pgmsas;

Example 2: Using a File as Input to an INFILE Statement

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);

SAS 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';

Example 3: Using Printer Options

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;