Chapter Contents

Previous

Next

FILENAME, FTP Access Method

Valid:	anywhere
Category:	Data Access

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

Operating Environment Information:   For details on 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, you do not need to specify a filename. Instead, put empty quotation marks in the statement. See Retrieving a Directory Listing.
Tip:	You can associate a fileref with a single file or with an aggregate file storage location.

host-options

specify host-specific details such as file attributes and processing attributes.

Operating Environment Information:   For a list of valid specifications, see the SAS documentation for your operating environment.  

FTP-Options

BLOCKSIZE=blocksize

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

Default:

8192

CD='directory'

issues a command that changes the working directory for the file transfer to the directory specified.

DEBUG

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

HOST='host'

where host is the network name of the remote host with the FTP server running.

Range:

You can specify either the name of the host (for example, server.pc.sas.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.

Default:

256

LS

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 LSTFILE= option in addition to LS.

LSFILE='character-string'

in combination with the LS option, specifies a character string that allows 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 files that start with sales and end with sas: filename foo ftp " ls lsfile='sales*.sas' other-ftp-options;

MGET

transfers multiple files, similar to the FTP command MGET.

Tip:	The whole transfer is treated like 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.

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, the remote host may require that you specify your e-mail address as the password.

PROMPT

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

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

Restriction:

For an IBM FTP server, this argument with the following command is required: rcmd='site rdw' The SITE RDW command is required for an IBM FTP server because, by default, this server removes the RDW (record descriptor word) that exists in the record before it is transferred. Issuing the SITE RDW command causes the IBM FTP server to include the RDW as part of the data.

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 are transferred in image (binary) mode.
S	is stream record format. Data are transferred in image (binary) mode. Interaction: The amount of data read is controlled by the current LRECL value or by the value of the NBYTE= variable in the FILE or 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 FILE statement and the NBYTE= optionin 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 and using an IBM Pascal FTP server, use the S370V or S370VS options instead of the RECFM= option. See S370V and S370VS below.

Default:

V

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.

Restriction:	This option works only with an IBM Pascal FTP server.
Interaction:	If you specify this option and the RECFM= option, SAS ignores the RECFM= option.
Tip:	The data are transferred in image or binary format, and are in local data format. Thus, you must use appropriate SAS informats to read the data correctly on non-EBCDIC hosts.

S370VS

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

Restriction:	This option works only with an IBM Pascal FTP server.
Interaction:	If you specify this option and the RECFM= option, SAS ignores the RECFM= option.
Tip:	The data are transferred in image or binary format and are in local data format. Thus, you must use appropriate SAS informats to read the data correctly on non-EBCDIC hosts.

USER='username'

where username is used to log in to the FTP server.

Interaction:

If PROMPT is specified, but USER= is not, 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 dilbert, and prompts dilbert for a password:

filename dir ftp '' ls user='dilbert' 
         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 they are required by the syntax, however, the statement includes empty quotation marks.  

Example 2: Reading a File from a Remote Host

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

filename myfile ftp 'data' 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 an OS/390 Host

This example reads an S370V-format file from an OS/390 system. See the RCMD= option for more information on RCMD='site rdw'.

filename viewdata ftp 'sluggo.stat.data'
         user='sluggo' host='mvshost1'
         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 login 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= 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: Importing a Transport Dataset

This example uses the CIMPORT procedure to import a transport data set from a host named mvshost1 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 full-qualified data set name, 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='sdcmvs.mvs.sas.com';

  proc cimport library=sasuser infile=inp;
  run;

Example 7: 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='mvhost1'
         lrecl=80 recfm=f blocksize=8000
     rcmd='site blocksize=8000 recfm=fb lrecl=80';

proc cport library=mylib file=inp;
run;

Example 8: 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 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;

Statements: FILENAME FILENAME, CATALOG Access Method FILENAME, SOCKET Access Method FILENAME, URL Access Method LIBNAME

Chapter Contents

Previous

Next

Top of Page

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