Using the FILENAME Statement or FTP for Foreign Files and Transport Files

Example: Using the FILENAME Statement for a File Transfer

CAUTION:

Use the FILENAME statement only for transport files, not foreign files.

Here is an example of using the FILENAME statement with the FTP access method to specify file attributes and to transfer a transport file over the network to a target computer:

filename tranfile ftp 'tport.dat' lrecl=80 blocksize=8000 
  recfm=f cd='mydir' host='myhost.mycompany.com' 
  user='myuser' pass='mypass' 
  rcmd='site umask 022 recfm=s';

The FILENAME statement specifies the fileref TRANFILE, which specifies the external file TPORT.DAT for transfer over the network. FTP options specify values for the record attributes: record length, block size, and record format. Also, FTP options identify the location for the file transfer on the target computer and the user ID and password that permit access to the target computer. Finally, the file mode creation mask on the target computer and a binary transfer are specified. For information about the FTP access method in the FILENAME statement, see the in SAS Statements: Reference and the companion documentation that is appropriate to your operating environment.

Note: Besides the FTP access method, you can also use the SOCKET, URL, or SMTP access method in the FILENAME statement. FTP directs the file to a hard disk, SOCKET directs the file to a TCP/IP port, URL directs the file to the Web, and SMTP directs the file to e-mail. For complete information about these access methods, seeFILENAME Statement, SOCKET Access Method in SAS Statements: Reference, FILENAME Statement, URL Access Method in SAS Statements: Referenceor FILENAME Statement, EMAIL (SMTP) Access Method in SAS Statements: Reference.

The FTP Utility

FTP is a user interface to the File Transfer Protocol. FTP copies files across a network connection between the source computer and a target computer. FTP runs from the initiating computer, which can be either the source computer or the target computer.

In order to transfer a file to a target computer across a network, a binary (or image) format transfer must be specified. This format guarantees a consistent file structure for any operating environment that runs SAS. You must use the FTP BINARY command to declare binary format. For typical FTP command syntax, see Example: Using FTP to Transfer Foreign Files and Transport Files.

Transferring a file in ASCII format places extra characters in the transport file on the target computer. Usually, these characters are line feeds, carriage returns, end-of-record markers, and other characters that some operating environments use to define file characteristics.

Target computers that run SAS expect a transport file to be formatted in a certain structure, without these characters. The introduction of these characters into a file causes corruption, which prevents the file from being successfully restored at the target computer. Error messages usually warn of file corruption. For details about file corruption and recovery actions, see Preventing and Fixing Problems.

Note: SAS 6.11 through SAS 9 support the FILENAME statement with the FTP access method, which specifies file attributes for file transfer. Releases before SAS 6.11 do not support the FILENAME statement with the FTP access method.

Example: Using FTP to Transfer Foreign Files and Transport Files

You transfer a foreign file in the same way that you transfer a transport file. The only difference between the two is the filename. SAS appends a transport filename with an appropriate member type extension, such as .DAT for a data set. A file that was created with CEDA features is appended with an appropriate SAS 9 or SAS 8 filename extension, such as .SAS9BDAT for a data set.

In these examples, TRANFILE specifies the name of the transport file that is transferred across the network. TARGET specifies the destination for the file in foreign format or the transport file on the target computer.

This example shows FTP commands that are used at the source computer to put a foreign file or a transport file on the target computer:

/* putting transport file on the target computer    */
  > open target-computer
  > binary
  > put tranfile target-computer-filename
  > close
  > quit

This example shows FTP commands that are used at the target computer to get a foreign file or a transport file from the source computer:

/* At the target computer, getting transport file from */
/* the source computer                                 */
  > open source-computer
  > binary
  > get tranfile source-computer-filename
  > close
  > quit

If you have access to a UNIX system, see the ftp(1) manual page for more details.

Note: In order to copy a file with the FTP put command to a server location, you must have write permission to the target location on the server. Because a local user's permission to put a file at a server location is uncertain, it is recommended that the remote user use the FTP get command to obtain the file from the client instead. The local user must give read and write permission to the file that the remote user accesses.

This code shows an example of user JOE at the target computer getting two transport files from an OpenVMS source computer:

   hp> ftp myhost.mycompany.com  1
   Connected to myhost.mycompany.com
   220 myhost.mycompany.com MultiNet FTP Server Process V4.0(15)
     at Mon 13-Jan-03 12:59PM-EDT
   Name (myhost.mycompany.com:): joe
   331 User name (joe) ok. Password, please.
   Password:
   230 User JOE logged into DISK01:[JOE] at Mon 13-Jan-03 
     12:59PM-EDT, job 27a34cef.
   Remote system type is VMS.
   ftp> cd [.xpttest]  2 
   250 Connected to DISK01:[JOE.XPTTEST].
   ftp> binary 80  3 
   200 Type I ok.
   ftp> get xptds.dat xptds.dat  4         
   200 Port 14.83 at Host 10.26.2.45 accepted.
   150 IMAGE retrieve of DISK01:[JOE.XPTTEST]XPTDS.DAT;1 started.
   226 Transfer completed.  1360 (8) bytes transferred.  5 
   1360 bytes received in 0.02 seconds (87.59 Kbytes/s)
   ftp> get xptlib.dat xptlib.dat  6 
   200 Port 14.84 at Host 10.26.2.45 accepted.
   150 IMAGE retrieve of DISK01:[JOE.XPTTEST]XPTLIB.DAT;1 started.
   226 Transfer completed.  3120 (8) bytes transferred.  7 
   3120 bytes received in 0.04 seconds (85.81 Kbytes/s)
   ftp> quit  8

1From an HP-UX operating environment, the user invokes FTP to connect to the OpenVMS operating environment MYHOST.MYCOMPANY.COM.

2After a connection is established between the HP-UX source computer and the OpenVMS target computer, at the FTP prompt, the user JOE changes to the directory on the target computer that contains transport file XPTTEST.

3 Transport file attributes BINARY 80 indicate that the OpenVMS transport file be transferred to the source computer in BINARY format in 80-byte records.

4 The FTP command gets the transport file named XPTDS.DAT from the target computer and copies it to a new file that has the same name, XPTDS.DAT, in the current directory.

5Messages indicate that the transfer was successful and that the length of the transport file was 1360 bytes.

6The FTP command gets another transport file named XPTLIB.DAT from the target computer and copies it to a new file that has the same name, XPTLIB.DAT, in the current directory.

7Messages indicate that the transfer was successful and that the length of the transport file was 3120 bytes.

8The user quits the FTP session.

Example: Using a Magnetic Medium to Transfer Foreign Files and Transport Files

When transferring a transport file by means of tape, always use an unlabeled tape. Although using a standard labeled tape is possible, it usually requires extra work to read the file at the target computer.

Also, if the transport file exceeds the capacity of one tape, then problems might occur during the restoration process. Rather than using multi-volume tapes, you should divide the original library into two or more libraries and create a separate tape for each one. The original library can be rebuilt at the target computer.

At the source computer, use the LIBNAME statement to assign the transport file to a magnetic medium as shown in these examples:

UNIX

libname
                                 tranfile xport `/dev/tape';

Windows

libname
                                 tran xport `a:\test';

Specification of the file path varies by operating environment.

The method used to move the transport file to a physical tape also varies by operating environment.

Here is a UNIX example:

dd if=tranfile of=/dev/tape1 bs=8000;

At the source computer, the UNIX dd command copies the specified input file to the specified output device. Block size is 8000.

At the target computer, you must copy the transport file from tape to disk.

Here is a UNIX example:

dd if=/dev/tape1 of=tranfile bs=8000;

At the target computer, you use the LIBNAME statement to translate the transport file to native format, assigning the resulting translated file to a specific file location.

Here is a UNIX example:

libname tranfile xport '/dev/tape1';