Statements

FILENAME Statement, URL Access Method

Enables you to access remote files by using the URL access method.

Valid:	anywhere
Category:	Data Access

Syntax
Arguments
Details
Examples
	Example 1: Accessing a File at a Web Site
	Example 2: Specifying a User ID and a Password
	Example 3: Reading the First 15 Records from a URL File
See Also

Syntax

FILENAME fileref URL 'external-file'
<url-options>;

Arguments

fileref

is a valid fileref.

Tip:	The association between a fileref and an external file lasts only for the duration of the SAS session or until you change it or discontinue it with another FILENAME statement. You can change the fileref for a file as often as you want.

URL

specifies the access method that enables you to read a file from any host computer that you can connect to on a network with a URL server running.

Alias:

HTTP

'external-file'

specifies the name of the file that you want to read from on a URL server. The Secure Socket Layer (SSL) protocol, https, can also be used to access the files. The file must be specified in one of these formats:

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

Operating Environment Information: For details about specifying the physical names of external files, see the SAS documentation for your operating environment. [cautionend]

url-options

can be any of the following:

AUTHDOMAIN="auth-domain"

specifies the name of an authentication domain metadata object in order to connect to the proxy or Web server. The authentication domain references credentials (user ID and password) without your having to explicitly specify the credentials. The auth-domain name is case sensitive, and it must be enclosed in double quotation marks.

An administrator creates authentication domain definitions while creating a user definition with the User Manager in SAS Management Console. The authentication domain is associated with one or more login metadata objects that provide access to the proxy or Web server and is resolved by the BASE engine calling the SAS Metadata Server and returning the authentication credentials.

Requirement:	The authentication domain and the associated login definition must be stored in a metadata repository, and the metadata server must be running in order to resolve the metadata object specification.
Interaction:	If you specify AUTHDOMAIN=, you do not need to specify USER= and PASS=.
See also:	For more information about creating and using authentication domains, see the discussion on credential management in the SAS Intelligence Platform: Security Administration Guide.

BLOCKSIZE=blocksize

where blocksize is the size of the URL data buffer in bytes.

Default:

DEBUG

writes debugging information to the SAS log.

Tip:	The result of the HELP command is returned as records.

HEADERS=fileref

specifies the fileref to which the header information is written when a file is opened by using the URL access method. The header information is the same information that is written to the SAS log.

Requirement:	The fileref must be defined in a previous FILENAME statement.
Interaction:	If you specify the HEADERS= option without specifying the DEBUG option, the DEBUG option is automatically turned on.
Interaction:	By default, log information is overwritten. To append the log information, you must specify the MOD option in the FILENAME statement that creates the fileref.

LRECL=lrecl

where lrecl is the logical record length of the data.

Default:	256
Interaction:	Alternatively, you can specify a global logical record length by using the LRECL= system option.

PASS='password'

where password is the password to use with the user name that is specified in the USER option.

Tip:	You can specify the PROMPT option instead of the PASS option, which tells the system to prompt you for the password.
Tip:	To use an encoded password, use the PWENCODE procedure in order to disguise the text string, and then enter the encoded password for the PASS= option. For more information, see the PWENCODE Procedure in the Base SAS Procedures Guide.

PPASS='password'

where password is the password to use with the user name that is specified in the PUSER option. The PPASS option is used to access the proxy server.

Tip:	You can specify the PROMPT option instead of the PPASS option, which tells the system to prompt you for the password.
Tip:	To use an encoded password, use the PWENCODE procedure to disguise the text string, and then enter the encoded password for the PASS= option. For more information, see the PWENCODE procedure in the Base SAS Procedures Guide.

PROMPT

specifies to prompt for the user login password if necessary.

Tip:	If you specify PROMPT, you do not need to specify PASS= or PPASS=.

PROXY=url

specifies the Uniform Resource Locator (URL) for the proxy server in one of these forms:

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

PUSER='username'

where username is used to log on to the URL proxy server.

Tip:	If you specify puser='*' , then the user is prompted for an ID.
Interaction:	If you specify the PUSER option, the USER option goes to the Web server regardless of whether you specify a proxy server.
Interaction:	If PROMPT is specified, but PUSER is not, the user is prompted for an ID as well as a password.

RECFM=recfm

where recfm is one of three record formats:

is fixed-record format. Thus, all records are of size LRECL with no line delimiters. Data is transferred in image (binary) mode.

is stream-record format. Data is transferred in image (binary) mode.

Alias:	N
Tip:	The amount of data that is read is controlled by the current LRECL value or the value of the NBYTE= variable in the INFILE statement. The NBYTE= option specifies a variable that is equal to the amount of data to be read. This amount must be less than or equal to LRECL.
See Also:	The NBYTE= option in the INFILE statement.

is variable-record format (the default). In this format, records have varying lengths, and they are transferred in text (stream) mode.

Tip:	Any record larger than LRECL is truncated.

Default:

TERMSTR='eol-char'

where eol-char is the line delimiter to use when RECFM=V. There are four valid values:

CR	carriage return (CR).
CRLF	carriage return (CR) followed by line feed (LF).
LF	line feed only (the default).
NULL	NULL character (0x00).

Default:	LF
Restriction:	Use this option only when RECFM=V.

USER='username'

where username is used to log on to the URL server.

Tip:	If you specify user='*' , then the user is prompted for an ID.
Interaction:	If you specify the USER option but do not specify the PUSER option, where the USER option goes depends on whether you specify a proxy server. If you do not specify a proxy server, USER goes to the Web server. If you do specify a proxy server, USER will go to the proxy server. If you specify the PUSER option, the USER option goes to the Web server regardless of whether you specify a proxy server.
Interaction:	If PROMPT is specified, but USER or PUSER is not, the user is prompted for an ID as well as a password.

Details

The Secure Sockets Layer (SSL) protocol is used when the URL begins with "https" instead of "http". The SSL protocol provides network security and privacy. Developed by Netscape Communications, SSL uses encryption algorithms that include RC2, RC4, DES, tripleDES, IDEA, and MD5. Not limited to providing only encryption services, SSL can also perform client and server authentication and use message authentication codes. SSL is supported by both Netscape Navigator and Internet Explorer. Many Web sites use the protocol to provide confidential user information such as credit card numbers. The SSL protocol is application independent, enabling protocols such as HTTP, FTP, and Telnet to be layered transparently above it. SSL is optimized for HTTP.

Operating Environment Information: Using the FILENAME statement requires information that is specific to your operating environment. The URL access method is fully documented here, but for more information about how to specify filenames, see the SAS documentation for your operating environment. [cautionend]

Examples

Example 1: Accessing a File at a Web Site

This example accesses document test.datat site www.a.com:

filename foo url 'http://www.a.com/test.dat'
         proxy='http://www.gt.sas.com';

Example 2: Specifying a User ID and a Password

This example accesses document file1.html at site www.b.com using the SSL protocol and requires a user ID and password:

filename foo url 'https://www.b.com/file1.html'
         user='jones' prompt;

Example 3: Reading the First 15 Records from a URL File

This example reads the first 15 records from a URL file and writes them to the SAS log with a PUT statement:

filename foo url 
    'http://support.sas.com/techsup/service_intro.html';
       
data _null_;
   infile foo length=len;
   input record $varying200. len;
   put record $varying200. len;
   if _n_=15 then stop;
run;