SAS/CONNECT User's Guide

Syntax for the PROC DOWNLOAD Statement

PROC DOWNLOAD <data-set-option(s)>

<catalog-option(s)>

<library-option(s)>

<external-file-option(s)>

<AFTER=date>

<CONNECTSTATUS=NO>;

data-set-options can be one or more of the following:

CONSTRAINT=NO

DATA=remote-SAS-data-set

EXTENDSN=NO

INDEX=NO

OUT=local-SAS-data-set

TRANIN=

TRANNET=

TRANOUT=

V6TRANSPORT
catalog-options can be one or more of the following:

ENTRYTYPE=etype

EXTENDSN=NO

INCAT=remote-SAS-catalog

OUTCAT=local-SAS-catalog
library-options are the following:

CONSTRAINT=NO

EXTENDSN=NO

GEN=YES

INDEX=NO

INLIB=remote-SAS-library

MEMTYPE=(mtype-list)

OUTLIB=local-SAS-library

V6TRANSPORT
external-file-options are the following:

BINARY

INFILE=remote-file-identifier

OUTFILE=local-file-identifier

PROC DOWNLOAD Statement Options

The following options can be used with the PROC DOWNLOAD statement. They are shown in alphabetical order.

AFTER=date

specifies a modification date in the form of a numeric date value or a SAS date constant.

This option is valid for transferring data sets, catalogs, and libraries and results in data sets or catalog entries being transferred only if they have been modified on or after the specified date.

Note: This option is available in Releases 6.09E, 6.11, TS040, and later. [cautionend]

For example, the following statements cause the transfer of data sets only if they have been modified on or after the specified date.

   /************************************/
   /* Download all data sets that have */
   /* been modified in the last week.  */
   /************************************/
rsubmit;
   data _null_;
   today=date();
   lastweek=today-7;
   call symput('lastweek',lastweek);
   run;
   proc download in=perm out=work 
      after=&lastweek memtype=data;
   run;
endrsubmit;

If your local session is using an earlier release that does not support this option, PROC DOWNLOAD still executes this option because the remote host has the input data set.

BINARY

specifies that you want to download a binary image (an exact copy) of an external remote host file. Use this option only for downloading external files.

The BINARY option prevents record delimiters from being inserted at each host record. In addition, if the remote host uses a different method of data representation, the BINARY option prevents any data translation such as conversion from EBCDIC to ASCII. See The BINARY Option for more information.

CONNECTSTATUS=NO CSTATUS=NO STATUS=NO

specifies that the status window should not be displayed while the data set, the catalog, the library, or the external file is being downloaded. By default, the DOWNLOAD procedure displays the Transfer Status window.

CONSTRAINT=YES|NO

specifies if integrity constraints should be re-created on the local host, when a SAS data set that has integrity constraints defined is downloaded. You can specify this option with the DATA= option (if you omit the OUT= option) or with the INLIB= and OUTLIB= options.

Note: By default, integrity constraints are re-created when you download a SAS library or when you download a single SAS data set and omit the OUT= option. If you specify the OUT= option with the DATA= option, the integrity constraints are not re-created. [cautionend]

DATA=remote-SAS-data-set

names a SAS data set that you want to download from the remote host to your local host. If the data set is a permanent SAS data set, you must define a libref before the PROC DOWNLOAD statement and specify the two-level name of the data set.

If you specify the name of a data view in the DATA= option, the materialized data is downloaded to the local host, not to the view definition.

If you do not use the DATA=, INCAT=, or INFILE= option, the last SAS data set that was created on the remote host during your SAS session is downloaded.

If you use the DATA= option, you must either use the OUT= option or omit all other options.

Using the DATA= option, SAS/CONNECT supports the transfer of long named members for data set transfers, as long as the host supports long member names.

ENTRYTYPE=etype
ETYPE=etype
ET=etype

specifies a catalog entry type to be downloaded. You can use this option only when you specify both the INCAT= and OUTCAT= options. See Using the ENTRYTYPE= Option for more information.

EXTENDSN=NO|YES

specifies whether or not to promote the length of short numerics (length less than 8 bytes) when transferring.

NO

indicates that the length of numeric variables is not promoted. This is the default.

YES

indicates that 1 will be added to the length of any numeric variable that has a length of less than 8 bytes before it is transferred to the target host. The behavior of this option differs based on the release that is being used.

When both the local and remote hosts are Version 7 or Version 8 and the V6TRANSPORT option is specified, the default behavior is to promote the length of numerics whose lengths are less than 8 bytes. This is consistent with Version 6 behavior. To override this behavior, specify EXTENDSN=NO along with the V6TRANSPORT option in the DOWNLOAD statement.
When the local host is Version 7 or Version 8 and the remote host is Version 6, neither the V6TRANSPORT nor the EXTENDSN= options are supported or recognized.
When the local host is Version 6 and the remote host is Version 7 or Version 8, numerics that have lengths of less than 8 WILL be promoted by default. In this case, EXTENDSN=NO should be specified to override the Version 6 default and prevent the promotion from occurring. This also means that the V6TRANSPORT option is neither recognized nor supported.

In Version 6 style translation, translation occurs twice for every transmission. The data is translated from local to transport format, and then the receiving host translates from transport format to local format. Two translations occur for all data that is transferred.

When both the local host and the remote host are Version 7 or Version 8, the translation rules have changed. First, no translation occurs if both the remote and local hosts have the same machine representations. This prevents any unnecessary translation from occurring. If translation is needed, the receiving host translates the data directly into its native representation. So, when both the local and remote hosts are running Version 7 or Version 8, the data is translated only one time when translation is necessary and is not translated when both hosts have the same machine architecture.

GEN=YES|NO

specifies that data set generations are to be sent during library transfers.

YES: data set generations are sent during library transfers. This is the default.
NO: data set generations are not sent during library transfers.

INCAT=remote-SAS-catalog

names a SAS catalog that you want to download from the remote host to your local host. If the catalog is stored in a permanent SAS data library, you must define a libref before specifying the PROC DOWNLOAD statement, and you must specify the catalog's two-level name. To download all of the catalogs in a SAS data library, specify

INCAT=libref._ALL_

If you specify this form for the INCAT= option, you must specify the same form for the OUTCAT= option.

You can transfer catalogs with entries that contain graphics output as well as other catalog entries.

Using the INCAT= option, SAS/CONNECT supports the transfer of long-named members for catalog transfers, as long as the host supports long member names.

INLIB=remote-SAS-library
IN=remote-SAS-library
INDD=remote-SAS-library

names a SAS data library that you want to download from the remote host to your local host. All three forms of this option are equivalent. This option must be used with the OUTLIB= option (in any of its forms). Before using this option, you must define the libref that is used for remote-SAS-library.

The following examples illustrate some valid pairs of these options:

INLIB= OUTLIB=

INLIB= OUT=

IN= OUT=

IN= OUTDD=

INDD= OUTDD=

INDD= OUTLIB=

INDEX=NO

specifies that when you download a SAS data set that has an index, the index is not re-created on the local host. You can specify this option with the DATA= option (if you omit the OUT= option) or by using the INLIB= and OUTLIB= options. Note that the index is re-created by default when you download a single data set and omit the OUT= option, or when you download a SAS data library.

If you specify the OUT= option with the DATA= option, the index is not re-created. To create an index for the output data set, use the INDEX= data set option in the data set name that you specify in the OUT= option to define the index. The INDEX= data set option is described in SAS Language Reference: Dictionary.

INFILE=remote-file-identifier

specifies the external file that you want to download from the remote host to the local host. remote-file-identifier can be one of the following:

fileref

is used if you have defined a fileref on the remote host that is associated with a single file. You must define the fileref before specifying the PROC DOWNLOAD statement.

fileref(member)

is used if you have defined a fileref on the remote host that is associated with an aggregate storage location, such as a directory or a partitioned data set. member then specifies the particular file(s) to transfer in that aggregate storage location. An asterisk (*) can be used as a wildcard character in the member specification to transfer

all files in the specified location (*).
all files that have the same extension (*.extension).
all files that have the same name but different extensions (name.*).

You must define the fileref before specifying the PROC DOWNLOAD statement. Refer to the SAS documentation for your remote host for more information about this use of filerefs.

The following example demonstrates how to use a wildcard to transfer (download) all files that have the extension .sas and are located in a directory on the remote UNIX host to a folder on a local PC.

filename locref 'c:\';
rsubmit;
   filename fref '/local/programs';
   proc download infile=fref('*.sas') 
                 outfile=locref;
   run;
endrsubmit;

'external-file-name'

is used to explicitly define the file that is to be downloaded.

If you use the INFILE= option, you must also use the OUTFILE= option.

MEMTYPE=(mtype-list)
MT=(mtype-list)
MTYPE=(mtype-list)

specifies one or more member types to be downloaded. You can specify this option only with the INLIB= and OUTLIB= options. See Using the MEMTYPE= Option for more information.

OUT=local-SAS-data-set

names the SAS data set on the local host to which you want the downloaded data set written. If you want to create a permanent SAS data set, you must define the libref before specifying the PROC DOWNLOAD statement, and you must specify a two-level SAS data set name.

Using the OUT= option, SAS/CONNECT supports the transfer of long-named members for data set transfers, as long as the host supports long member names.

The OUT= option is a valid form of the OUTLIB= option. The DOWNLOAD procedure determines how to interpret the meaning of the OUT= option as follows:

When you specify the DATA= option and the OUT= option, the OUT= option names the output SAS data set.
For example, if the USER= option is set to MYLIB, the following statement downloads the data set A from the library MYLIB on the remote host to the library MYLIB on the local host:
```
proc download data=a out=a;
run;
```
If you specify only the OUT= option, the DOWNLOAD procedure downloads the last SAS data set that was created on the remote host.
For example, the following statement downloads the last data set that was created on the remote host to the data set MYDATA in the library MYLIB on the local host (assuming USER=MYLIB).
```
proc download out=mydata;
run;
```
When you specify the INLIB= option (or some other form of this option) with the OUT= option, the OUT= option specifies the name of a SAS data library. For example, the following statement downloads all of the data sets and catalogs that are in the library A on the remote host to the library RMTLIB on the local host:
```
proc download inlib=a out=rmtlib;
run;
```

See Default Naming Conventions for Downloaded Data Sets for information about the effect of omitting the OUT= option.

OUTCAT=local-SAS-catalog

names the SAS catalog on the local host to which you want the downloaded catalog written. If you want to create a permanent SAS catalog, you must define the libref before specifying the PROC DOWNLOAD statement and you must specify a two-level SAS catalog name. To download all of the catalogs in a SAS data library, specify

OUTCAT=libref._ALL_

If you specify this form for the OUTCAT= option, you must specify the same form for the INCAT= option.

If you use the OUTCAT= option, you must also use the INCAT= option.

Using the OUTCAT= option, SAS/CONNECT supports the transfer of long-named members for catalog transfers, as long as the host supports long member names.

OUTFILE=local-file-identifier

identifies an external file on the local host to which you want a downloaded external file written. local-file-identifier can be one of the following:

fileref

is used if you have defined a fileref on the local host that is associated with a single file. You must define the fileref before specifying the PROC DOWNLOAD statement.

fileref(member)

is used if you have defined a fileref on the local host that is associated with an aggregate storage location such as a directory. member then specifies the particular file in that aggregate storage location. You must define the fileref before specifying the PROC DOWNLOAD statement. Refer to the SAS documentation for your local host for more information about this use of filerefs.

Note: If a wildcard (*) is used in the INFILE= option, then OUTFILE=fileref should point to an aggregate storage location such as a directory. [cautionend]

'external-file-name'

is used to explicitly define the file that is to be downloaded.

If you use the OUTFILE= option, you must also use the INFILE= option.

OUTLIB=local-SAS-library
OUT=local-SAS-library
OUTDD=local-SAS-library

names the destination SAS data library on your local host where the downloaded data sets and catalogs from the remote host are stored. All three forms of this option are equivalent. Before using this option, you must define the libref that is used for local-SAS-library.

Note: The OUT= form of this option is the same as the OUT= option that is used to specify a SAS data set. When you use this option, the DOWNLOAD procedure determines whether the input option was DATA= or INLIB= and processes the downloaded objects appropriately. [cautionend]

The OUTLIB= option must be used with the INLIB= option, but you can use any form of the OUTLIB= option with any form of the INLIB= option. Refer to the description of the INLIB= option for examples that illustrate some valid pairs of these options.

TRANIN=translation-table-name

specifies a translation table to be used when transferring a data set that is stored in a different data representation than that of the remote host.

For example, FTP was used to transfer a data set from a UNIX machine to a remote VAX, and now you want to transfer the data set for use on your PC. The data set is not in the native VAX format (the remote host), so the default translation table will not work. Using the TRANIN= option with PROC DOWNLOAD, you can specify a translation table that transfers the data from UNIX to the PC.

The translation will take place on the remote host before the data is transferred to the local host. This option is equivalent to using the TRANTAB= data set option on the input data set.

Note: This option is only valid for data set transfers between two Version 7 or Version 8 sessions and when the transfer is between two hosts that have different machine architectures, which makes translation necessary. [cautionend]

TRANNET=translation-table-name

specifies a translation table to be used when transferring a data set between remote and local hosts that have different machine architectures. The translation table specified will be used in place of the default translation table. The translation will take place on the local host after the data is transferred from the remote host.

TRANOUT=translation-table-name

specifies a translation table to be used when transferring a remote data set to a local host, and the OUTREP= data set option indicates a data representation different from the native data representation of the local host. The translation will take place on the local host after the data is transferred from the remote host.

For example, you are using a PC and would like to transfer a data set from a UNIX machine, and the OUTREP=VAX_VMS data set option is specified in a DATA statement. Using the TRANOUT= option with PROC DOWNLOAD, you can specify a translation table that transfers the data set from the remote UNIX machine to your local PC in a VAX format.

V6TRANSPORT

specifies that data should be translated in the Version 6 style. This option should only be specified when the Version 6 translation style you want and both the local and remote hosts are Version 7 or Version 8. Version 6 style translation means that the data is translated from a local format to a transport format, and then the receiving host translates the data from the transport format to a local format.

When V6TRANSPORT is specified, the default behavior is to promote the length of numerics that are less than 8 bytes. The EXTENDSN=NO option may be used with the V6TRANSPORT option to prevent the lengths from being promoted.

When transferring files from Version 7 or Version 8 to Version 6, SAS/CONNECT checks that the files are Version 6 compliant. If the files are not Version 6 compliant, an error message is issued and the transfer is terminated. For example, a data set from a Version 7 or Version 8 session that contains a variable with a long name will not transfer because Version 6 does not support long variable names.

Data set and variable names are truncated if they exceed the Version 6 maximum. A warning message is issued about the truncation, but the transfer will continue.

In Version 6, the value of a character variable has a maximum length of 200. For Version 7 or Version 8, this maximum has been increased to 32K. Therefore, a Version 7 or Version 8 variable value that has a length that is greater than 200 will transfer to a Version 6 variable, but the value is truncated to 200. A warning message is issued about the truncation, but the transfer will continue.

Default Naming Conventions for Downloaded Data Sets

Follow these rules when you download a SAS data set and do not specify the name of the data set in the OUT= option:

If the input data set (the data set that is specified in the DATA= option) has a two-level name and the same libref that is defined for the input data set is also defined in the local host environment, the data set is downloaded to the library on the local host that is associated with that libref. The data set has the same member name on the local host.
For example, suppose you submit the following statement:
```
libname orders 
   local-host-SAS-data-library;
```
If you remote submit the following statements, the data set ORDERS.QTR1 is downloaded to ORDERS.QTR1 on the local host.
```
   /*******************************************/
   /* The libref ORDERS is defined on both    */
   /* hosts.                                  */
   /*******************************************/
libname orders 
   remote-host-SAS-data-library;
proc download data=orders.qtr1;
run;
```
If the input data set has a two-level name but the libref for the input data set is not also defined in the local host environment, the data set is downloaded to the default library on the local host. This is usually the WORK library, but the library may also be defined by using the USER libref.
The data set retains the same data set name that it had on the remote host. For example, if you remote submit the following statements, the data set is downloaded to WORK.QTR2 on the local host.
```
   /*******************************************/
   /* The libref ORDERS is defined only on    */
   /* the remote host.                        */
   /*******************************************/
libname orders 
   remote-host-SAS-data-library;
proc download data=orders.qtr2;
run;
```

If the input data set has a one-level name and the default libref on the remote host also exists on the local host, the data set is downloaded to that library.

For example, suppose you submit the following statement:

libname orders 
   local-host-SAS-data-library;
libname local 
   local-host-SAS-data-library;
   /************************************/
   /* This option has no effect in     */
   /* this case.                       */
   /************************************/
options user=local;

If you remote submit the following statements, the data set ORDERS.QTR1 is downloaded to ORDERS.QTR1 on the local host.

   /*******************************************/
   /* The libref ORDERS is defined on both    */
   /* hosts.                                  */
   /*******************************************/
libname orders 
   remote-host-SAS-data-library;
options user=orders;
proc download data=qtr1;
run;

If the input data set has a one-level name and the default libref on the remote host does not exist on the local host, the data set is downloaded to the default library on the local host. That is, the USER libref on the local host is used only if the USER libref on the remote host does not exist on the local host.
For example, suppose you submit these statements:
```
libname local 
   local-host-SAS-data-library;
options user=local;
```
When you remote submit the following statements, the data set ORDERS.QTR1 is downloaded to LOCAL.QTR1 on the local host.
```
   /*******************************************/
   /* The libref ORDERS is defined only on    */
   /* the remote hosts.                       */
   /*******************************************/
libname orders 
   remote-host-SAS-data-library;
options user=orders;
proc download data=qtr1;
run;
```
If you omit the DATA= option, as in this example,
```
proc download;
run;
```
the last data set that was created on the remote host during the SAS session is downloaded to the local host.

The naming conventions on the local host follow one of the rules described above, depending on how the last data set created was named.

Data Set Options and Attributes for the DOWNLOAD Statement

PROC DOWNLOAD permits you to specify SAS data set options in the DATA= and OUT= options. Note that SAS data set options are not supported with the INLIB= and OUTLIB= options, even when you download only data sets. The data set options must be associated with a specific SAS data set, so they must be used in the DATA= or OUT= options.

In addition, when you download SAS data sets by using the DATA= option (omitting the OUT= option) or the INLIB= and OUTLIB= options, or if you omit all of these options, the following characteristics are inherited by the downloaded data set.

Note: The following list of characteristics shows the SAS data set option (in parenthesis) that was used to create the characteristic for the original data set. You do not have to specify the option to have it inherited when the data set is downloaded. [cautionend]

password for ALTER protection (ALTER= SAS data set option)
compressed observations (COMPRESS= SAS data set option).
indexes (INDEX= SAS system option or other methods of creating indexes).
Note: The index for a downloaded SAS data set is re-created on the local host; it is not copied from the remote host. To prevent the re-creation of the index, you can specify the INDEX=NO option in the PROC DOWNLOAD statement, as described in PROC DOWNLOAD Statement Options.
data set label (LABEL= SAS data set option)
password for READ protection (READ= SAS data set option)
re-use of free space in compressed data sets (REUSE= SAS data set option)
list of variables that the data set is sorted by (SORTEDBY= SAS data set option)
data set type (TYPE= SAS data set option)
password for WRITE protection (WRITE= SAS data set option)
integrity constraints
maximum generations.

If you specify the OUT= option when downloading a single data set, only the following characteristics are inherited by the downloaded data set:

data set type
data set label.

The following example illustrates the use of the DATA= option and the INDEX=NO option. The example also shows the use of the KEEP= SAS data set option. Note that because no OUT= option is specified, the downloaded data set inherits the characteristics of the input data set except the index (because the INDEX=NO option is specified).

proc download data=study(keep=age score1 score2) index=no;
run;

Chapter Contents
Previous
Next
Top of Page