FILENAME Statement, FTP Access Method | SAS 9.1 Language Reference Dictionary, Volumes 1, 2 and 3

Enables you to access remote files by using the FTP protocol

Valid: anywhere

Category: Data Access

Syntax

FILENAME fileref FTP external-file < ftp-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.

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

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 Information: For details about specifying the physical names of external files, see the SAS documentation for your operating environment.
Tip: 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 Example 1 on page 1196.
Tip: You can associate a fileref with a single file or with an aggregate file storage location.
Tip: 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 Information: For more information on some of these FTP options, see the SAS documentation for your operating environment.

FTP Options

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.
Tip: 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.
Tip: 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.
Tip: 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.
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.
Featured in: Example 10 on page 1198

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): User s Guide .
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.

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 machine (for example, 190.96.6.96 ).

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.

LRECL= lrecl

where lrecl is the logical record length of the data.
Default: 256

issues the LS command to the FTP server. LS returns the contents of the working directory as records with no file attributes.
Tip: The file attributes that are returned will vary, depending on the FTP server that is being accessed.
Tip: 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.
Tip: You can specify a wildcard as part of character-string .
Tip: 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.
Tip: 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.
Tip: 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.
Tip: The NEW option will be ignored if the directory exists.
Restriction: The NEW option is not available under z/OS.

PASS= password

where password is the password to use with the user name 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: If the user name is anonymous , then the remote host might require that you specify your e-mail address as 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 Base SAS Procedures Guide .
Featured in: Example 6 on page 1197

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.

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 instance, 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.
Tip: You can specify multiple FTP service commands if you separate them by semicolons.

Examples:

 rcmd='ascii;site unmask 002'  rcmd='stat;site chmod 0400 ~aclin/abc.txt'

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.

Alias: BINARY

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

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 Also: The NBYTE= option on page 1227 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.

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.

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.
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 on non-EBCDIC hosts .
Tip: 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.
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 on non-EBCDIC hosts.
Tip: 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.

USER= username

where username is used to log in to the FTP server.
Restriction: The USER option is not available under z/OS for batch processing.
Interaction: If PROMPT is specified, but USER= is not, then the user is prompted for an ID.

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 . 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 the RCMD= on page 1194 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= on page 1193 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 Data Library

This example uses the CPORT procedure to transport a SAS data 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 data 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 XMPORT engine. The PROC COPY step copies all data sets from the SAS data 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-data-library  ';  libname inp xport;  proc copy in=mylib out=inp mt=data;  run;  proc contents data=inp._all_;  run;

Example 10: Reading and Writing from Directories

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

 filename indir ftp '/u/directory1' DIR                     host="login001.unx.mycompany.com"                     user="xxxx" prompt;  filename outdir ftp '/u/directory2' DIR                     host="login011.unx.mycompany.com"                     user="xxxx" prompt;  data _null_;     infile indir(ftpmem1) truncover;     input;     file outdir(ftpout1);     put _infile_;     infile indir(ftpmem2) truncover;     input;     file outdir(ftpout2);     put _infile_;  run;