The DOWNLOAD Procedure

PROC DOWNLOAD Statement

Transfers files from the server to the client.

Valid in:	client session
Category:	Data Access

Syntax

PROC DOWNLOAD

<data-set-option(s)>
<catalog-option(s)>
<library-option(s)>
<external-file-option(s)>
<AFTER=date>
<CONNECTSTATUS=YES | NO>;

Syntax Description

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

CAUTION:
Do not confuse the PROC DOWNLOAD data set options with the SAS data set options.
The PROC DOWNLOAD data set options are valid only in the context of PROC DOWNLOAD. However, two of the PROC DOWNLOAD data set options -- DATA= and OUT= -- can be further characterized by SAS data set options. For details, see the sections on the DATA= option and the OUT= option.

CONSTRAINT YES | NO

DATA=server-SAS-data-set

DATECOPY

EXTENDSN=YES | NO

INDEX=YES | NO

OUT=client-SAS-data-set

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

ENTRYTYPE=etype

EXTENDSN=YES | NO

INCAT=server-SAS-catalog

OUTCAT=client-SAS-catalog
library-options can be one or more of the following:

CONSTRAINT=YES | NO

EXTENDSN=YES | NO

GEN=YES | NO

INDEX=YES | NO

INLIB=server-SAS-library

MEMTYPE=(mtype-list)

OUTLIB=client-SAS-library

VIEWTODATA

V6TRANSPORT
external-file-options are the following:

BINARY

INFILE=server-file-identifier

OUTFILE=client-file-identifier

PROC DOWNLOAD Statement Options

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. Its use results in data sets or catalog entries being transferred only if they have been modified on or after the specified date.

The AFTER= option is also valid for external file transfers between most computers. If a computer is unable to perform the transfer, this message is displayed:

ERROR: AFTER= not supported on this platform. 
NOTE: The SAS System stopped processing this step
      because of errors.

Note: The AFTER= option is available in SAS 6.09E, SAS 6.11, TS040, and later. [cautionend]

For example, the following statements cause the transfer of data sets only if they were modified within the last week.

   /************************************/
   /* 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 client session is using an earlier release of SAS that does not support the AFTER= option, PROC DOWNLOAD still executes this option because the server has the input data set.

BINARY

specifies a download of a binary image (an exact copy) of an external server file. Use this option only for downloading external files.

Note: External files are files that are not SAS files. [cautionend]

By default, if the client and server run in different operating environments (for example, UNIX and Windows), PROC DOWNLOAD transfers a file from the client to the server, translating the file from UNIX representation to Windows representation. PROC DOWNLOAD also inserts record delimiters that are appropriate for the target environment.

You do not always want to translate a file. For example, you might need to download executable files from the server to the client and later upload them back to the server. Binary file format also saves resources for users who store their own files and for system backups. The BINARY option prevents delimiters from being inserted for each file record that is created at the client. In addition, if the client and server use a different method of data representation, the BINARY option prevents any data translation between ASCII and EBCDIC.

For an example of using the BINARY option, see Example 10. DTS: Distributing an .EXE File from the Server to Multiple Clients.

CONNECTSTATUS=YES | NO

specifies whether the Transfer Status window should be displayed during a transfer. By default, the DOWNLOAD procedure displays the Transfer Status window.

Alias:	CSTATUS=, STATUS=
Default:	YES

CONSTRAINT=YES | NO

specifies if integrity constraints should be re-created on the client 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.

By default, integrity constraints are re-created only 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.

DATA=server-SAS-data-set <(SAS-data-set-option(s))>

specifies a SAS data set that you want to download from the server to the client. 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 client, not to the view definition.

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

Requirements:	If you specify the DATA= option, you must either use the OUT= option or omit all other options.
Featured In:	Specifying Data Set Options for the DATA= and OUT= Options in PROC UPLOAD and PROC DOWNLOAD
See:	SAS data set options in SAS Language Reference: Dictionary.
See Also:	OUT= option

DATECOPY

retains the date on which a SAS data set was created and the date on which a SAS data set was last modified for each data set that is transferred.

ENTRYTYPE=etype

specifies a catalog entry type to be downloaded. Examples of catalog entry types include DATA and FORMAT.

Alias:	ETYPE=, ET=
Requirements:	To use this option, you must also specify the INCAT= and OUTCAT= options.

EXTENDSN=YES | NO

specifies whether 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.
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 client computer.

The behavior of the EXTENDSN= option varies according to the SAS release that is used.

If both the client and the server run SAS 8 or a later release, and the V6TRANSPORT option is specified, the default is to promote the length of the numeric variable whose length is less than 8 bytes. This is consistent with SAS 6 behavior. To override this behavior, specify EXTENDSN=NO along with the V6TRANSPORT option in the DOWNLOAD statement.
If either the client or the server runs SAS 6, neither the V6TRANSPORT nor the EXTENDSN= option is supported or recognized.
If the client runs SAS 6 and the server runs SAS 8 or a later release, a numeric variable whose length is less than 8 bytes is promoted by default. In this case, specify EXTENDSN=NO in order to override the SAS 6 default and to prevent the promotion.

See File Format Translation Algorithms for information about translating file formats between a client and server that run on computers whose internal representations are incompatible.

Default:

GEN=YES | NO

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

YES: specifies that data set generations are sent during library transfers.
NO: specifies that data set generations are not sent during library transfers.

Default:

YES

INCAT=server-SAS-catalog

names a SAS catalog that you want to download from the server to your client. If the catalog is stored in a permanent SAS 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 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.

CAUTION:

Some catalog entry types are not compatible between SAS releases.

If you attempt to download a catalog entry from a server to a client and they run different SAS releases, the client catalog entry that is being downloaded might not be supported at the client. In this case, the catalog entry will not be transferred and the following error message is displayed:

WARNING: FILEFMT entries

INDEX=YES | NO

specifies whether to re-create an index at the client when you download a SAS data set. You can specify this option when using the DATA= option (if you omit the OUT= option) or when using the INLIB= and OUTLIB= options.

If you download a single data set and omit the OUT= option, or if you download a SAS library, the index is re-created by default.

If you specify the OUT= option and the DATA= option, the index is not re-created.

INFILE=server-file-identifier

specifies the external file that you want to download from the server to the client.

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

server-file-identifier can be one of the following:

fileref

is used if you have defined a fileref on the server 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 server that is associated with an aggregate storage location, such as a directory or a partitioned data set. member specifies one or more files in that aggregate storage location that should be transferred. An asterisk (*) can be used as a wildcard character in the member specification of the files to transfer. Here are the only valid uses of the asterisk wildcard character:

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

You must define the fileref before specifying the PROC DOWNLOAD statement. For details about filerefs, see the appropriate documentation for your operating environment.

This example shows how to use a wildcard to transfer all files whose filenames have the extension .sas and are located in a directory on a server that runs UNIX to a folder on a client that runs Windows.

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.

INLIB=server-SAS-library

specifies a SAS library to download from the server to the client. 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 server-SAS-library.

Alias:

INDD=, IN=

MEMTYPE=(mtype-list)

specifies one or more member types to be downloaded.

Here are the valid member types:

ALL
CATALOG
DATA
MDDB
VIEW

Alias:	MTYPE=, MT=
Requirements:	To use this option, you must also specify the INLIB= and OUTLIB= options.

OUT=client-SAS-data-set <(SAS-data-set-option(s))>

names the SAS data set on the client that you want the downloaded data set written to. 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.

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

If 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 server to the library MYLIB on the client:
```
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 server.

For example, the following statement downloads the last data set that was created on the server to the data set MYDATA in the library MYLIB on the client (assuming USER=MYLIB).
```
proc download out=mydata;
run;
```
If you specify the INLIB= option and the OUT= option, the OUT= option specifies the name of a SAS library.

For example, the following statement downloads all of the data sets and catalogs that are in the library A on the server to the library RMTLIB on the client:
```
proc download inlib=a out=rmtlib;
run;
```

For details about the effect of omitting the OUT= option, see Default Naming Conventions for Downloaded Data Sets.

Featured In:	Specifying Data Set Options for the DATA= and OUT= Options in PROC UPLOAD and PROC DOWNLOAD
See:	SAS data set options in SAS Language Reference: Dictionary
See Also:	DATA= option

OUTCAT=client-SAS-catalog

names the SAS catalog on the client that you want the downloaded catalog written to. 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 library, specify OUTCAT=libref._ALL_.

Requirements:

If you specify the OUTCAT= option, you must also specify the INCAT= option. If you specify _ALL_ in the OUTCAT= option, you must also specify _ALL_ in the INCAT= option.

Tip:

If you transfer a catalog that contains entries of type PROGRAM, you must compile the entries on the target operating environment before execution. To compile all the PROGRAM entries in a catalog, submit (or remotely submit) the following statements:

proc build cat=libref.member-name batch;
   compile;
run;

libref identifies the SAS library that contains the catalog and member-name identifies the catalog.

OUTFILE=client-file-identifier

identifies an external file on the client that you want a downloaded external file written to.

client-file-identifier can be one of the following:

fileref

is used if you have defined a fileref on the client 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 client that is associated with an aggregate storage location such as a directory. member specifies which file in that aggregate storage location should be transferred. You must define the fileref before specifying the PROC DOWNLOAD statement. For details about filerefs for your operating environment, see the appropriate operating environment companion documentation.

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.

Requirements:

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

OUTLIB=client-SAS-library

names the destination SAS library on your client where the downloaded data sets and catalogs from the server are stored. All three forms of this option are equivalent. Before using this option, you must define the libref that is used for client-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 the OUTLIB= 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. See the description of the INLIB= option for examples that illustrate some valid pairs of these options.

Alias:

OUTDD=, OUT=

VIEWTODATA

for a library transfer only, causes view descriptor files to be transferred as data sets instead of as view files, which is the default. If you want some views to be transferred as view files and other views to be transferred as data sets, you would have to perform two separate transfers. If you attempt to use this option for a single data set transfer (by using the DATA= option), an error results.

V6TRANSPORT

specifies that data should be translated by using the SAS 6 data translation algorithm. Specify this option only when you want to use the SAS 6 translation style explicitly and both the client and the server run SAS 8 or a later release of SAS.

When V6TRANSPORT is specified, the default behavior is to promote a numeric variable whose length is less than 8 bytes. To prevent a promotion of this length, you can use the EXTENDSN=NO option along with the V6TRANSPORT option.

Default Naming Conventions for Downloaded Data Sets

If you omit the OUT= option, which specifies the name of the output data set, from the DOWNLOAD statement, SAS follows these rules to determine the name for the data set:

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 client environment, the data set is downloaded to the library on the client that is associated with that libref. The data set has the same member name on the client.

For example, suppose you submit the following statement:
```
libname orders 
   client-SAS-library;
```
If you remotely submit the following statements, the data set ORDERS.QTR1 is downloaded to ORDERS.QTR1 on the client.
```
   /*******************************************/
   /* The libref ORDERS is defined on both    */
   /* the client and server.                  */
   /*******************************************/
libname orders 
   server-SAS-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 client environment, the data set is downloaded to the default library on the client. This is usually the WORK library, but the library might also be defined by using the USER libref.

The data set retains the same data set name that it had on the server. For example, if you remotely submit the following statements, the data set is downloaded to WORK.QTR2 on the client.
```
   /*******************************************/
   /* The libref ORDERS is defined only on    */
   /* the server.                             */
   /*******************************************/
libname orders 
   server-SAS-library;
proc download data=orders.qtr2;
run;
```

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

For example, suppose you submit the following statement:

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

If you remotely submit the following statements, the data set ORDERS.QTR1 is downloaded to ORDERS.QTR1 on the client.

   /*******************************************/
   /* The libref ORDERS is defined on both    */
   /* hosts.                                  */
   /*******************************************/
libname orders 
   server-SAS-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 server does not exist on the client, the data set is downloaded to the default library on the client. That is, the USER libref on the client is used only if the USER libref on the server does not exist on the client.

For example, suppose you submit these statements:
```
libname local 
   client-SAS-library;
options user=local;
```
When you remotely submit the following statements, the data set ORDERS.QTR1 is downloaded to LOCAL.QTR1 on the client.
```
   /*******************************************/
   /* The libref ORDERS is defined only on    */
   /* the servers.                            */
   /*******************************************/
libname orders 
   server-SAS-library;
options user=orders;
proc download data=qtr1;
run;
```
If you omit the DATA= option, the last data set that was created on the server during the SAS session is downloaded to the client, as follows:
```
proc download;
run;
```
The naming conventions on the client follow one of the previously described rules, based on how the last data set was created.

Top of Page

	CONSTRAINT YES \| NO
	DATA=server-SAS-data-set
	DATECOPY
	EXTENDSN=YES \| NO
	INDEX=YES \| NO
	OUT=client-SAS-data-set
	V6TRANSPORT

	ENTRYTYPE=etype
	EXTENDSN=YES \| NO
	INCAT=server-SAS-catalog
	OUTCAT=client-SAS-catalog

	CONSTRAINT=YES \| NO
	EXTENDSN=YES \| NO
	GEN=YES \| NO
	INDEX=YES \| NO
	INLIB=server-SAS-library
	MEMTYPE=(mtype-list)
	OUTLIB=client-SAS-library
	VIEWTODATA
	V6TRANSPORT

	BINARY
	INFILE=server-file-identifier
	OUTFILE=client-file-identifier