 |
|
| Statements |
FILENAME Statement, FTP Access Method
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
- 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.
- '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.
![[cautionend]](../../../../common/63294/HTML/default/images/cautend.gif)
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 Retrieving a Directory Listing. 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 about some of these FTP options, see the SAS documentation for your operating environment.
| 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 also: 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.
Tip: 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. 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: 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 Also: Encoding Values in SAS Language Elements in the 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 Also: LOWCASE_MEMNAME option Featured in: 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 Also: 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. - 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 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.
- 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 thePWENCODE Procedure in the Base SAS Procedures Guide. Featured in: Using an Encoded Password - 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.
- 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.
- 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.
Alias: 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 Also: 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.
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.
- S370VS
-
indicates that the file that is being read is in IBM 370 variable-spanned format.
- USER='username'
-
where username is used to log in to the FTP server.
- 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. - 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= 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= 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 myshost1for 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 The 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 FILEEXT .
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 listing close; ods html body='body.html' path=output; proc print data=sashelp.class;run; ods html close; ods listing;
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 listing close; ods html body='body.html' path=output1 gpath=output2 frame='frames.html' contents='contents.html'; proc gtestit;run;quit; ods html close; ods listing;
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;
| See Also |
|
|
|
|
Copyright © 2011 by SAS Institute Inc., Cary, NC, USA. All rights reserved.