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.

FTP: specifies the access method that enables you to use File Transfer Protocol (FTP) to read from or write to a file from any host computer that you can connect to on a network with an FTP server running.

Tip:Use FILENAME with FTP when you want to connect to the host computer, to log in to the FTP server, to make records in the specified file available for reading or writing, and to disconnect from the host computer.

'external-file': specifies the physical name of an external file that you want to read from or write to. The physical name is the name that is recognized by the operating environment.

If the file has an IBM 370 format and a record format of FB or FBA, and if the ENCODING= option is specified, then you must also specify the LRECL= option. If the length of a record is shorter than the value of LRECL, then SAS pads the record with blanks until the record length is equal to the value of LRECL.

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

Tips:If you are not transferring a file but performing a task such as retrieving a directory listing, then you do not need to specify a filename. Instead, put empty quotation marks in the statement. See Retrieving a Directory Listing.

You can associate a fileref with a single file or with an aggregate file storage location.

If you use the DIR option, specify the directory in this argument.

ftp-options: specifies details that are specific to your operating environment such as file attributes and processing attributes.

Operating environment:For more information about some of these FTP options, see the SAS documentation for your operating environment.

See:FTP Options

FTP Options

AUTHDOMAIN="auth-domain": specifies the name of an authentication domain metadata object in order to connect to the FTP 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 FTP 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:For more information about creating and using authentication domains, see the discussion on credential management in the SAS Intelligence Platform: Security Administration Guide.

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

The BINARY option overrides the value of RECFM= in the FILENAME FTP statement, if specified, and forces a binary transfer.

Alias:RECFM=F

Interaction:If you specify the BINARY option and the S370V or S370VS option, then SAS ignores the BINARY option.

BLOCKSIZE=blocksize: where blocksize is the size of the data buffer in bytes.

Default:32768

CD='directory': issues a command that changes the working directory for the file transfer to the directory that you specify.

Interaction:The CD and DIR options are mutually exclusive. If both are specified, FTP ignores the CD option and SAS writes an informational note to the log.

DEBUG: writes to the SAS log informational messages that are sent to and received from the FTP server.

DIR: enables you to access directory files or PDS/PDSE members. Specify the directory name in the external-file argument. You must use valid directory syntax for the specified host.

Interaction:The CD and DIR options are mutually exclusive. If both are specified, FTP ignores the CD option and SAS writes an informational note to the log.

Tips:If you want FTP to append a file extension of DATA to the member name that is specified in the FILE or INFILE statement, then use the FILEEXT option in conjunction with the DIR option. The FILEEXT option is ignored if you specify a file extension in the FILE or INFILE statement.

If you want FTP to create the directory, then use the NEW option in conjunction with the DIR option. The NEW option will be ignored if the directory exists.

If the NEW option is omitted and you specify an invalid directory, then a new directory will not be created and you will receive an error message.

The maximum number of directory or z/OS PDSE members that can be open simultaneously is limited by the number of sockets that can be open simultaneously on an FTP server. The number of sockets that can be open simultaneously is proportional to the number of connections that are set up during the installation of the FTP server. You might want to limit the number of sockets that are open simultaneously to avoid performance degradation.

Example:Reading and Writing from Directories

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.

Default:SAS assumes that an external file is in the same encoding as the session encoding.

Tip:The data is transferred in image or binary format and is in local data format. Thus, you must use appropriate SAS informats to read the data correctly.

See:Encoding Values in SAS Language Elements in SAS National Language Support (NLS): Reference Guide

FILEEXT: specifies that the member type of DATA is automatically appended to the member name in the FILE or INFILE statement when you use the DIR option.

Tip:The FILEEXT option is ignored if you specify a file extension in the FILE or INFILE statement.

See:LOWCASE_MEMNAME option

Example:Reading and Writing from Directories

HOST='host': where host is the network name of the remote host with the FTP server running.

You can specify either the name of the host (for example, server.pc.mydomain.com) or the IP address of the computer (for example, 2001:db8::).

HOSTRESPONSELEN='size': where size is the length of the FTP server response message.

Default:2048 bytes

Range:2048 to 16384 bytes

Restriction:If you specify a size that is less than 2048 or is greater than 16384, the size will be set to 2048.

LIST: issues the LIST command to the FTP server. LIST returns the contents of the working directory as records that contain all of the file attributes that are listed for each file.

Tip:The file attributes that are returned will vary, depending on the FTP server that is being accessed.

LOWCASE_MEMNAME: enables autocall macro retrieval of lowercase directory or member names from FTP servers.

Restriction:SAS autocall macro retrieval always searches for uppercase directory member names. Mixed case directory or member names are not supported.

Interaction:If you access files off FTP servers by using the %INCLUDE, FILE, INFILE, or other DATA step I/O statements, case sensitivity will be preserved.

See:FILEEXT option

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 in SAS System Options: Reference.

LS: issues the LS command to the FTP server. LS returns the contents of the working directory as records with no file attributes.

Tips:The file attributes that are returned will vary, depending on the FTP server that is being accessed.

To return a listing of a subset of files, use the LSFILE= option in addition to LS.

LSFILE='character-string'

in combination with the LS option, specifies a character string that enables you to request a listing of a subset of files from the working directory. Enclose the character string in quotation marks.

Restriction:LSFILE= can be used only if LS is specified.

Tips:You can specify a wildcard as part of 'character-string '.

The file attributes that are returned will vary, depending on the FTP server that is being accessed.

Example:This statement lists all of the files that start with sales and end with sas:

filename myfile ftp '' ls lsfile='sales*.sas' 
   other-ftp-options;

MGET: transfers multiple files, similar to the FTP command MGET.

Tips:The whole transfer is treated as one file. However, as the transfer of each new file is started, the EOV= variable is set to 1.

Specify MPROMPT to prompt the user before each file is sent.

MPROMPT: specifies whether to prompt for confirmation that a file is to be read, if necessary, when the user executes the MGET option.

Restriction:The MPROMPT option is not available on z/OS for batch processing.

NEW: specifies that you want FTP to create the directory when you use the DIR option.

Restriction:The NEW option is not available under z/OS.

Tip:The NEW option will be ignored if the directory exists.

PASS='password': where password is the password to use with the user name specified in the USER= option.

Tips:You can specify the PROMPT option instead of the PASS option, which tells the system to prompt you for the password.

If the user name is anonymous, then the remote host might require that you specify your e-mail address as the password.

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 Base SAS Procedures Guide.

Example:Using an Encoded Password

PASSIVE: specifies that an attempt is made for passive mode FTP.

In passive mode FTP, the client initiates the control and data connections to the server. This action solves the problem of firewalls filtering the incoming data port connection to the client from the server.

Note:Not all FTP servers support the passive mode. If an attempt is made by the FILENAME statement FTP access method to issue the PASV command and the command fails or the server does not accept the command, then active mode FTP is used for the connection.

PORT=portno: where portno is the port that the FTP daemon monitors on the respective host.

The portno can be any number between 0 and 65535 that uniquely identifies a service.

Tip:In the Internet community, there is a list of predefined port numbers for specific services. For example, the default port for FTP is 21. A partial list of port numbers is usually available in the /etc/services file on any UNIX computer.

PROMPT: specifies to prompt for the user login password, if necessary.

Restriction:The PROMPT option is not available for batch processing under z/OS.

Interaction:If PROMPT is specified without USER=, then the user is prompted for an ID, as well as a password.

Tip:You can use the SAVEUSER option to save the user ID and password after the user ID and password prompt is successfully executed.

RCMD= 'command '

where command is the FTP 'SITE' or 'service' command to send to the FTP server.

FTP servers use SITE commands to provide services that are specific to a system and are essential to file transfer but not common enough to be included in the protocol.

For example,

rcmd='site
                              rdw'

preserves the record descriptor word (RDW) of a z/OS variable blocked data set as a part of the data. See S370V and S370VS below.

Interaction:Some FTP service commands might not run at a particular client site depending on the security permissions and the availability of the commands.

Tips:If you transfer a file with the FTP access method and then cannot read the file, you might need to change the FTP server's UMASK setting.

If the FTP server supports a SITE UMASK setting, you can change the permissions of the file as shown in the following example:

filename in ftp '/mydir/accounting/file2.dat'
   host="xxx.fyi.xxx.com"
   user="john"
   rcmd='site umask 022'
   prompt;
data _null;
file in;
put a $80;
run;

You can specify multiple FTP service commands if you separate them by semicolons. Some examples are as follows:

rcmd='ascii;site umask 002'
rcmd='stat;site chmod 0400 ~mydir/abc.txt'

RECFM=recfm

where recfm is one of three record formats:

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

Aliases:BINARY

The BINARY option overrides the value of RECFM= in the FILENAME FTP statement, if specified, and forces a binary transfer.

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

Interaction:The amount of data that is read is controlled by the current LRECL value or by 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:The NBYTE= option in the INFILE statement.

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

Interaction:Any record larger than LRECL is truncated.

Tip: If you are using files with the IBM 370 Variable format or the IBM 370 Spanned Variable format, then you might want to use the S370V or S370VS options instead of the RECFM= option. See S370V and S370VS below.

Default:V

Interaction: If you specify the RECFM= option and the S370V or S370VS option, then SAS ignores the RECFM= option.

RHELP: issues the HELP command to the FTP server. The results of this command are returned as records.

RSTAT: issues the RSTAT command to the FTP server. The results of this command are returned as records.

SAVEUSER: saves the user ID and password after the user ID and password prompt are successfully executed.

Interaction:The user ID and password are saved only for the duration of the SAS session or until you change the association between the fileref and the external file, or discontinue it with another FILENAME statement.

S370V: indicates that the file being read is in IBM 370 variable format.

Interaction: If you specify this option and the RECFM= option, then SAS ignores the RECFM= option.

Tips:The data is transferred in image or binary format and is in local data format. Thus, you must use appropriate SAS informats to read the data correctly on non-EBCDIC hosts.

Use the rcmd='site rdw' option when you transfer a z/OS data set with a variable-record format to another z/OS data set with a variable-record format to preserve the record descriptor word (rdw) of each record. By default, most FTP servers remove the rdw that exists in each record before it is transferred.

Typically, the 'SITE RDW' command is not necessary when you transfer a data set with a z/OS variable-record format to ASCII, or when you transfer an ASCII file to a z/OS variable-record format.

S370VS: indicates that the file that is being read is in IBM 370 variable-spanned format.

Interaction: If you specify this option and the RECFM= option, then SAS ignores the RECFM= option.

Tips:The data is transferred in image or binary format and is in local data format. Thus, you must use appropriate SAS informats to read the data correctly on non-EBCDIC hosts.

Use the rcmd='site rdw' option when you transfer a z/OS data set with a variable-record format to another z/OS data set with a variable-record format to preserve the record descriptor word (rdw) of each record. By default, most FTP servers remove the rdw that exists in each record before it is transferred.

Typically, the 'SITE RDW' command is not necessary when you transfer a data set with a z/OS variable-record format to ASCII, or when you transfer an ASCII file to a z/OS variable-record format.

TERMSTR='eol-char'

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

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 in to the FTP server.

Restriction:The FTP access method does not support FTP proxy servers that require user ID authentication.

Interaction:If PROMPT is specified, but USER= is not, then the user is prompted for an ID.

Tip:You can specify a proxy server and credentials for an FTP server when using the FTP access method. The user ID and password that you need to log in to the FTP server is sent via the proxy server by using the user="userid@ftpservername" pass="password" host="proxy.server.xxx.com" syntax. Both anonymous and user ID validation are supported.

Example: Retrieving a Directory Listing

WAIT_MILLISECONDS=milliseconds: specifies the FTP response time in milliseconds.

Default:1,000 milliseconds

Tip: If you receive a “connection closed; transfer aborted” or “network name is no longer available” message in the log, use the WAIT_MILLISECONDS option to increase the response time.

Comparisons

As with the FTP get and put commands, the FTP access method lets you download and upload files. However, this method directly reads files into your SAS session without first storing them on your system.

Examples

Example 1: Retrieving a Directory Listing

This example retrieves a directory listing from a host named mvshost1 for user smythe, and prompts smythe for a password:

filename dir ftp '' ls user='smythe' 
   host='mvshost1.mvs.sas.com' prompt;
data _null_;
   infile dir;
   input;
   put _INFILE_;
run;

Note: The quotation marks are empty because no file is being transferred. Because quotation marks are required by the syntax, however, you must include them.

Example 2: Reading a File from a Remote Host

This example reads a file called sales in the directory /u/kudzu/mydata from the remote UNIX host hp720:

filename myfile ftp 'sales' cd='/u/kudzu/mydata'
   user='guest' host='hp720.hp.sas.com'
   recfm=v prompt;
data mydata / view=mydata;   /* Create a view */
   infile myfile;
   input x $10. y 4.;
run;
proc print data=mydata;     /* Print the data */
run;

Example 3: Creating a File on a Remote Host

This example creates a file called test.dat in a directory called c:\remote for the user bbailey on the host winnt.pc:

filename create ftp 'c:\remote\test.dat'
   host='winnt.pc'
   user='bbailey' prompt recfm=v;
data _null_;
   file create;
   do i=1 to 10;
      put i=;
   end;
run;

Example 4: Reading an S370V-Format File on z/OS

This example reads an S370V-format file from a z/OS system. See RCMD= option for more information about RCMD='

site
                     rdw

filename viewdata ftp 'sluggo.stat.data'
   user='sluggo' host='zoshost1'
   s370v prompt rcmd='site rdw';
data mydata / view=mydata;   /* Create a view */
   infile viewdata;
   input x $ebcdic8.;
run;
proc print data=mydata;     /* Print the data */
run;

Example 5: Anonymously Logging In to FTP

This example shows how to log in to FTP anonymously, if the host accepts anonymous logins.

Note: Some anonymous FTP servers require a password. If required, your e-mail address is usually used. See PASS= option under “FTP Options.”

filename anon ftp '' ls host='130.96.6.1' 
   user='anonymous';
data _null_;
   infile anon;
   input;
   list;
run;

Note: The quotation marks following the argument FTP are empty. A filename is needed only when transferring a file, not when routing a command. The quotation marks, however, are required.

Example 6: Using an Encoded Password

This example shows you how to use an encoded password in the FILENAME statement.

In a separate SAS session, use the PWENCODE procedure to encode your password and make note of the output.

proc pwencode in= "MyPass1";
run;

The following output appears in the SAS log:

(sas001)TX1QYXNzMQ==

You can now use the entire encoded password string in your batch program.

filename myfile ftp 'sales' cd='/u/kudzu/mydata'
   user='tjbarry' host='hp720.hp.mycompany.com'
   pass="(sas001)TX1QYXMZ==";

Example 7: Importing a Transport Data Set

This example uses the CIMPORT procedure to import a transport data set from a host named myshost1 for user calvin. The new data set will reside locally in the SASUSER library. Note that user and password can be SAS macro variables. If you specify a fully qualified data set name, then use double quotation marks and single quotation marks. Otherwise, the system will append the profile prefix to the name that you specify.

%let user=calvin;
%let pw=xxxxx;
filename inp ftp "'calvin.mat1.cpo'" user="&user"
   pass="&pw" rcmd='binary'
   host='mvshost1';
proc cimport library=sasuser infile=inp;
run;

Example 8: Transporting a SAS Library

This example uses the CPORT procedure to transport a SAS library to a host named mvshost1 for user calvin. It will create a new sequential file on the host called userid.mat64.cpo with the recfm of fb, lrecl of 80, and blocksize of 8000.

filename inp ftp 'mat64.cpo' user='calvin' 
   pass="xxxx" host='mvshost1'
   lrecl=80 recfm=f blocksize=8000
   rcmd='site blocksize=800 recfm=fb lrecl=80';
proc cport library=mylib file=inp;
run;

Example 9: Creating a Transport Library with Transport Engine

This example creates a new SAS library on host mvshost1. The FILENAME statement assigns a fileref to the new data set. Note the use of the RCMD= option to specify important file attributes. The LIBNAME statement uses a libref that is the same as the fileref and assigns it to the XPORT engine. The PROC COPY step copies all data sets from the SAS library that are referenced by MYLIB to the XPORT engine. Output from the PROC CONTENTS step confirms that the copy was successful:

filename inp ftp  'mat65.cpo' user='calvin' 
   pass="xxxx"  host='mvshost1'
   lrecl=80 recfm=f blocksize=8000
   rcmd='site blocksize=8000 recfm=fb lrecl=80';
libname mylib 'SAS-library';
libname inp xport;
proc copy in=mylib out=inp mt=data;
run;
proc contents data=inp._all_;
run;

Note: For more information about the XPORT engine, see Transport Engine in SAS Language Reference: Concepts and XPORT Engine Limitations in Moving and Accessing SAS Files.

Example 10: Reading and Writing from Directories

This example reads the file ftpmem1 from a directory on a UNIX host, and writes the file ftpout1 to a different directory on another UNIX host.

filename indir ftp '/usr/proj2/dir1' DIR
   host="host1.mycompany.com"
   user="xxxx" prompt;
filename outdir ftp '/usr/proj2/dir2' DIR FILEEXT
   host="host2.mycompany.com"
   user="xxxx" prompt;
data _null_;
   infile indir(ftpmem1) truncover;
   input;
   file outdir(ftpout1);
   put _infile_;
run;

The file ftpout1 is written to /usr/proj2/dir2/ftpout1.DATA. Note that a member type of DATA is appended to the ftpout1 file because the FILEEXT option was specified in the output file's FILENAME statement. For more information, see the FILEEXT option.

Note: The DIR option is not needed for some ODS destinations.

The following example writes an output file and transfers it to an ODS-specified destination. The DIR option is not needed.

filename output ftp "~user/ftpdir/" host="host.fyi.company.com" user="userid"  
pass="userpass" recfm=s debug;
ods html body='body.html' path=output;
proc print data=sashelp.class;run;

To export multiple graph files to a remote directory location, the DIR option must be specified in the FILENAME statement. Accordingly, when creating external graph files with the ODS HTML destination, two FILENAME statements are needed: one for the HTML files, and one for the graph files. The following example illustrates the need for two FILENAME statements.

filename output1 ftp "~user/dir" fileext host="host.unx.company.com"
   user="userid" pass="userpass" recfm=s debug;
filename output2 ftp "~user/dir" dir fileext host="host.unx.company.com"
   user="userid" pass="userpass" recfm=s debug;
ods html body='body.html' path=output1 gpath=output2
   frame='frames.html' contents='contents.html';
proc gtestit;
run;
quit;
;

Example 11: Using a Proxy Server

This example uses a proxy server with the FTP access method. The user ID and password are sent via the proxy server.

filename test ftp ' ' ls
   host='proxy.server.xxx.com'
   user='userid@ftpservername'
   pass='xxxxxx'
   cd='pubsdir/';
data _null_;
   infile test truncover;
   input a $256.;
   put a=;
run;

FILENAME Statement, FTP Access Method

Syntax

Arguments