Chapter Contents
Previous
Next
FILENAME

FILENAME


Associates a SAS fileref with an external file

Valid: anywhere
CMS specifics: fileref, device-type, file-specification, options

Syntax
Details
Tape Device Values
Host Option Values
Electronic Mail Option Values for the FILENAME Statement in the CMS Environment
Device Types for the FILENAME Statement in the CMS Environment
File Characteristics for Devices
Using the FILENAME Statement When a FILEDEF Command Has Been Issued
The FILEDEF command without the PERM option
The FILEDEF command with the PERM option
See Also

Syntax

FILENAME fileref device-type <'file-specification'> options;
FILENAME fileref <device-type> 'file-specification' | ('file-specification-1'... 'file-specification-n') options;
FILENAME fileref 'TAPn';
FILENAME fileref PIPE 'pipe-specification';
FILENAME fileref | _ALL_ CLEAR;
FILENAME fileref | _ALL_ LIST;
FILENAME fileref EMAIL 'address' <email-options>;

fileref
specifies the logical name that is to be associated with an external file, using 1-8 characters, with the first character either a letter (A-Z) or an underscore (_). For information on the CMS file naming conventions used by SAS, see SAS Filenames.

device-type
specifies the type of output or input device for the file. Valid values are
DISK
DUMMY
EMAIL
PRINTER
PUNCH
READER
TAPE
TERMINAL
In addition of the device types listed above, SAS also supports the following access methods: CATALOG, EMAIL, FTP, SOCKET, and URL. Access methods are specified the same way as device types in the FILENAME statement. See Device Types for the FILENAME Statement in the CMS Environment for further information.

'file-specification'
identifies the external file to be associated with the specified fileref. The file-specification can be in one of the following formats:

'filename filetype <filemode | SFS-directory | *>'
If you omit filemode or SFS-directory, or if you specify an asterisk (*) when referencing the file for input, accessed disks are searched in the standard CMS search order, and the first occurrence of a file with a matching filename and filetype is read. If you omit filemode or SFS-directory or if you specify an asterisk (*) when referencing the file for output, the file is written on the first R/W disk.

Note that you cannot use an asterisk (*) for either filename or filetype.

'filename MACLIB <filemode>'
Specifies a MACLIB as an aggregate external file.

'filemode | SFS-directory | *'
Specifies a CMS minidisk or SFS directory as an aggregate external file.

('filename-1 filetype-1 <filemode-1 | * | SFS-directory-1>'... 'filename-n filetype-n<filemode-n | * | SFS-directory-n>')
specifies a concatenation of files. Note that if file specification includes concatenated files, all files must have the same attributes. The concatenation can contain aggregate external files (SFS directories, MACLIBs, or minidisks).

options
In the CMS environment, the FILENAME statement accepts the following host options. When specifying more than one option, use a blank space to separate each option. All options use a keyword=value format. Valid keywords are:
BLKSIZE=
DENSITY=
DISP=
LABEL=
LRECL=
RECFM=
TRACK=
VOLID=

See Host Option Values for the values that can be assigned to the preceding options. See SAS Language Reference: Dictionary for information on portable options.

EMAIL
specifies the EMAIL device type, which indicates that the specified file is to be sent as electronic mail, using the specified email-options.

'address'

email-options
when the EMAIL device type is specified, the FILENAME statement accepts the following email-options:
ATTACH=
CC=
EMAILID=
EMAILSYS=
SUBJECT=
TO=
TYPE=

See Electronic Mail Option Values for the FILENAME Statement in the CMS Environment for the values that can be assigned to the preceding options.

'TAPn'
specifies the virtual address of the tape device for a file on tape. The value of n is an integer identifying the control unit or device. For example, CMS typically associates virtual address 181 with TAP1. If no external file is specified when the device type is TAPE, it defaults to TAP1. This is valid only when device is TAPE. See Tape Device Values for a listing of valid values.

PIPE 'pipe-specification'
specifies the external file as a CMS pipeline. A pipeline specification is comprised of one or more stages to which you want to route output or from which you want to read input.

The CMS pipeline specification follows the standard syntax for a CMS pipeline; that is it consists of an optional parenthesized list of CMS pipeline options followed by a sequence of one or more stages. The entire specification must be enclosed within a pair of single or double quotes. Comments delimited by /* */ may be contained within the quoted string. These comments are ignored.

For example, this FILENAME statement contains a valid CMS pipeline specification: 

filename adata pipe
   "(name adata)       /* name the pipeline */  
   < archive data a    /* read in a file */
   | unpack            /* unpack if necessary */
";

For further information, see Using CMS Pipelines .

_ALL_
can be specified to clear or list all currently allocated filerefs.

CLEAR
can be specified to deallocate the specified fileref, or to deallocate all currently allocated filerefs.

LIST
can be specified to list the fileref name and physical name, or to list information about all currently allocated filerefs.

Details

See SAS Language Reference: Dictionary for information about portable options and on clearing and listing filerefs.

Tape Device Values

The following table lists the symbolic names and corresponding virtual addresses for CMS tape output devices.

Symbolic Names for CMS Tape Output Devices
Symbolic Name VirtualAddress
 Symbolic Name VirtualAddress
TAP0 180 TAP8 288
TAP1 181 TAP9 289
TAP2 182 TAPA 28A
TAP3 183 TAPB 28B
TAP4 184 TAPC 28C
TAP5 185 TAPD 28D
TAP6 186 TAPE 28E
TAP7 187 TAPF 28F

Host Option Values

The following file characteristics can be specified in the options argument in a FILENAME statement. Refer to SAS Language Reference: Dictionary for information on portable options.

All options use a keyword=value format, and multiple options are separated by blank spaces.

Note that if file specification includes concatenated files, all files must have the same attributes.

BLKSIZE=value
specifies the buffer size allocated to contain records. Valid values are 1 through 65535.

Records do not have to be blocked; however, because disk or tape activity is reduced when records are blocked, it is more efficient to use blocks. Blocking records is different when using CMS Native I/O Services than when using OS/MVS Simulation Services.

For CMS Native I/O Services, the following apply:

For MVS Simulated I/O Services, the following apply:

DENSITY=value
specifies tape density in bits per inch. Valid values include 200, 556, 800, 1600, 6250, 38K.

DISP=value
specifies the status (disposition) of the file. Acceptable values are
MOD specifies that output lines are to be written after any existing lines in the file.
OLD specifies that any output lines are to be written at the beginning of the file. This is the default. For CMS, this option is identical to the NEW option.
NEW specifies that any output lines are to be written at the beginning of the file. For CMS, this option is identical to the OLD option.

FILEVAR=variable
allows you to dynamically change input and output files in the middle of a DATA step.

LABEL=value
indicates the type of label processing for a tape file. LABOFF is the default. Valid values are

If LABEL=SL, NL, or BLP is specified, an additional label value n can be specified after the SL, NL, or BLP. The value of n indicates the file position in a multifile volume. The default value is 1.

LEAVE=YES
indicates that a multifile tape is not repositioned at open for LABOFF or BLP processing. For SL tapes, LEAVE=YES does not reposition before label processing. Omitting LEAVE or specifying LEAVE=NO causes a tape to be rewound and repositioned each time a file is opened. (See Working with SAS Files on Tape for details on tape processing.)

LRECL=value
specifies the logical record length in bytes. Valid values are 1 through 65,535.

RECFM=format
specifies the format of records in the file.

You can choose one of the following record formats:
F specifies fixed-length records, unblocked.
FB specifies fixed-length records, blocked.
V specifies variable-length records, unblocked.
VB specifies variable-length records, blocked.
U specifies undefined-record format. For CMS disk files, this is the same as V.

You can use the following values in any of the previously listed formats except U.
A specifies that the first byte of each record is an ANSI printer control character and that the file is to be handled as a print file.
S specifies that the file contains spanned records (V), or the file contains standard blocks (F). FS, FBS, VS, and VBS files must be assigned with a CMS FILEDEF command.

SYSPARM=value
passes an option string to a tape management system for standard label tapes. Entering a question mark (?) causes SAS to prompt you for option settings.

TRACK=value
specifies the tape setting. Valid values are

VOLID=value
specifies the volume serial number to be verified in the tape. If the value contains any special characters, it must be enclosed in single quotes.

See the FILEDEF command entry in VM/ESA CMS Command Reference, for more information about these options.

For more information about other options available in the FILENAME statement, see SAS Language Reference: Dictionary.

If a variable-length file is opened for update (possibly in the DATA step) and if the replacement line is not the same length as the existing line, the standard CMS file system action truncates the file at that point. No message is given. The next read to that file returns EOF.

Electronic Mail Option Values for the FILENAME Statement in the CMS Environment

The FILENAME statement supports the following values for email-options, which are used in conjunction with the EMAIL device type to send mail from within a SAS session:

ATTACH='file-specification'
specifies the names of one or more files that will be attached to the outgoing message. The syntax rules for specifying a single file are as follows:

'filename <filetype <filemode | SFS-dir | *>>'

To attach multiple files, use: ('file1' 'file2' ... 'filen'), as shown in the following example: 

attach=('june94 txt .reports.june' 'july94 txt .reports.july')

CC='secondary-address'
specifies one or more names and addresses that will receive the message along with those listed in the TO= option. These names and addresses will appear on the CC line of the outgoing message. The following examples show the syntax used for single and multiple addresses: 
cc='joe@hisaddr.edu'
cc=("mark@work.com" "jane@play.org")

To specify a name along with an address, enclose the address in angle brackets (< >): 

cc='Joseph Smith <joe@hisaddr.edu>'

Recipients can also be specified as nicknames that will be resolved from the user's NAMES file.

EMAILID='from-user'
specifies the e-mail address that will appear on the From line in the electronic mail message. The default is the USERID and host name of the user running SAS. For a server application of SAS, you may prefer to supply a specific user name.

To specify the sender's name and address, include the address in angle brackets (< >), as follows: 

emailid='Joseph Smith <joe@hisaddr.edu>'

EMAILSYS='stage-specification'
overrides the value of the EMAILSYS= system option to send the message using a different CMS pipeline stage. See EMAILSYS= for details.

SUBJECT='message-subject'
specifies the information that will appear on the Subject line of the outgoing message. Use quotes if the Subject line includes special characters. If quotes are omitted, the Subject line is converted to uppercase text.

TO='to-address'
specifies one or more names and addresses that will receive the outgoing message. These names and addresses will appear on the To line of the outgoing message.

The following examples show the syntax for a single address and for multiple addresses: 

to='joe@hisaddr.edu'
to=('joe@hisaddr.edu' 'jane@play.org')

To include a name with an address, enclose the address in angle brackets (< >), as shown in the following example: 

to='Joseph Smith <joe@hisaddr.edu>'

Recipients can also be specified as nicknames that will be resolved from the user's NAMES file.

Device Types for the FILENAME Statement in the CMS Environment

The following devices are supported for reading and writing external files and can be specified in the device-type argument of the FILENAME statement. Note that when files are concatenated, all files in the list must be processed by the same external I/O device (for example, all disk or all reader files).

DISK
specifies that the file is to be read from or written to disk. This is the default, which does not have to be specified. This device type uses the native CMS interface.

DUMMY
specifies that output to the external file is to be discarded.

EMAIL
specifies that the file is to be sent out in electronic mail. For details on associated email-options, see Electronic Mail Option Values for the FILENAME Statement in the CMS Environment.

PIPE
specifies that the external file is a CMS pipeline, which enables you to receive input from any CP or CMS command or pipeline device driver, or to route output to any pipeline device driver. No options are valid with the PIPE device type. See Using CMS Pipelines for further details.

PRINTER
associates the fileref with the virtual printer. This device is for output only. Specifying this device type causes the CMS SAS interface to issue a FILEDEF for the device. Use the CP SPOOL and TAG commands to control the destination or use the FSFORMS command to set up printing forms. See Using the PRINT Command and the FORM Subsystem , for information about using the FSFORMS command.

PUNCH
associates the fileref with the virtual PUNCH. This device is for output only. Specifying this device type causes the CMS SAS interface to issue a FILEDEF for the device. Use the CP SPOOL and TAG commands to control the destination.

READER
specifies that the file is to be a reader file. The BLKSIZE= option is ignored for this device because CMS does not support blocking. This device is for input only. Specifying this device type causes the CMS SAS interface to issue a FILEDEF for the device. If you have more than one file in your reader, the one that is ordered first is read. Use the CP ORDER READER and CP QUERY READER commands to determine the order of your reader files.

TAPE
specifies that the file is in sequential format on tape. Specifying this device type causes the CMS SAS interface to issue a FILEDEF for the device.

TERMINAL
specifies that the file is to be read from or written to the terminal. The BLKSIZE= option is ignored for this device because CMS does not support blocking. This device type uses the Native CMS Interface.

File Characteristics for Devices

When you specify a device type on an external I/O statement, you can also specify values for file characteristics in the options argument. See Device Types for the FILENAME Statement in the CMS Environment for a list of the options. If you do not specify a value for a file characteristic, a default is used. See the following table, entitled "Default File Characteristics for Devices Other Than DISK" for information on default values. For DISK defaults, see the following table entitled "Default File Characteristics for Disk Files".

Default File Characteristics for Disk Files
Types of Files LRECL=
Option 		RECFM=
Option 		BLK-SIZE=
Option 		Line Length for Data
Nonprint files:



DATA step file I/O 80 FB 960 80
FILE from a window 136 V N/A * 136
Print files:



LISTING 257 VA N/A Determined by LINESIZE= system option; 256 maximum
SASLOG 257 maximum VA N/A Determined by LINESIZE= system option; 256 maximum
PRINT (from a window) Determined by data; 136 maximum VA N/A LRECL- 1
*N/A means that the BLKSIZE= option is not applicable for this type of file.

Default File Characteristics for Devices Other Than DISK
Device Type LRECL= Option RECFM=Option BLKSIZE=Option
PUNCH 80 FB 960
READER 80 F 80
TERMINAL 255 V 255
PRINTER 133 VA 137
TAPE 32760 U 32760
TEMP 80 FB 960
DUMMY 80 FB 960
PIPE n/a n/a n/a

Using the FILENAME Statement When a FILEDEF Command Has Been Issued

A FILENAME statement reassigns a logical name assignment made by a FILEDEF command, provided that the PERM option is not specified in the FILEDEF command. SAS does not interfere with FILEDEF options that are already specified. Therefore, TAPE options that are specified in the FILE, FILENAME, or INFILE statements that conflict with an existing FILEDEF to TAPE are ignored. See Working with SAS Files on Tape for more information. If the device specified in the FILENAME statement does not result in SAS issuing a FILEDEF command, then it does not matter whether a CMS FILEDEF command with the PERM option has already assigned the fileref.

See Device Types for the FILENAME Statement in the CMS Environment to determine whether SAS issues a FILEDEF command for a device. Here are some examples:

The FILEDEF command without the PERM option

Assume the following FILEDEF command is in effect: 

FILEDEF MYDATA PUNCH

Then you can issue the following FILENAME statement: 

filename mydata punch;

The FILENAME statement associates the virtual PUNCH with the fileref MYDATA. This works because the devices are the same. Now issue the following FILENAME statement: 

filename mydata printer;

This FILENAME statement references the virtual printer to the fileref MYDATA. The devices are different, but the PERM option is not in the FILEDEF command. Therefore the FILENAME statement that assigns MYDATA to the printer overrides the FILEDEF command. And, because PRINTER is another device that requires a filedef, a new FILEDEF command is issued.

The following FILENAME statement also reassigns the fileref, this time to the disk file TASTEST DATA *: 

filename mydata 'tastest data';

The FILEDEF command with the PERM option

Now, assume that the following FILEDEF command with the PERM option is in effect: 

FILEDEF MYDATA PUNCH (PERM

Then you can issue the following FILENAME statement to reference the virtual PUNCH: 

filename mydata punch;

Both the FILEDEF command and the FILENAME statement reference the virtual punch.

Now issue the following FILENAME statement: 

filename mydata printer;

This statement results in the message that the fileref is not available. The FILEDEF command was issued with the PERM option, and the devices that were referenced by the logical name MYDATA do not match.

Now issue the following FILENAME statement: 

filename mydata  'tastest data c';

This FILENAME statement assumes the default device DISK. Notice that device DISK uses the Native CMS Interface. This means that the FILENAME statement does not issue a FILEDEF command. Because a second FILEDEF command to the logical name MYDATA is not issued, the PERM option has no effect. When SAS searches for filerefs, it looks first at those assigned by the FILENAME statement, then at those assigned by the CMS FILEDEF command. So, in this case, instead of associating the fileref MYDATA with the virtual PUNCH, SAS associates it with the DISK file TASTEST DATA C.
See Also


Chapter Contents
Previous
Next
Top of Page

Copyright 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.