RETRIEVE_PACKAGE

Arguments

pkgListId

identifies the list of packages.

Type:	Numeric
Direction:	Output

retrievalType

specifies the transport to use when retrieving a package. Valid values include the following:

• FROM_QUEUE

• FROM_ARCHIVE

• FROM_WEBDAV

Type:	Character
Direction:	Input

retrievalInfo

specifies transport-specific information that determines the package to retrieve. When retrieving from an archive, specify the physical path and name of the archive, excluding the extension. When retrieving from a WebDAV-compliant server, specify the URL that identifies the package to retrieve. When retrieving from MSMQ queues, use the following syntax:

MSMQ://queueHostMachineName\queueName

When retrieving from MQSeries queues, use the following syntax:

MQSERIES://queueManager:queueName

or

MQSERIES-C://queueManager:queueName

Type:	Character
Direction:	Input

totalPackages

provides the total number of packages found.

Type:	Numeric
Direction:	Output

rc

receives a return code.

Type:	Numeric
Direction:	Output

properties

identifies a comma-separated list of optional property names. Valid property names are as follows:

• CORRELATIONID

• FTP_PASSWORD

• FTP_USER

• HTTP_PASSWORD

• HTTP_PROXY_URL

• HTTP_USER

• NAMESPACES

• QUEUE_TIMEOUT

Type:	Character
Direction:	Input

propValue1, ...propValueN

specifies a value for each specified property name. The order of the property values must match the order of the property names specified in the properties parameter. Valid property values are defined as follows:

CORRELATIONID

This character string specifies retrieval of only those packages that have the specified correlation identifier. (Applies only to the message queue transport.)

FTP_PASSWORD

When retrieving with the archive transport (FROM_ARCHIVE), this character string indicates the password that is used to connect to the remote host. Specify this property only when the host does not accept anonymous access. (Applies to the FROM_ARCHIVE property when the FTP protocol is used.)

FTP_USER

When retrieving with the archive transport, this character string indicates the name of the user to connect to the remote host. (Applies to the FROM_ARCHIVE property when the FTP protocol is used.)

HTTP_PASSWORD

When retrieving with the WebDAV transport (FROM_WEBDAV), this character string indicates the password used to bind to the Web server. Specify this property only when the Web server does not accept anonymous access. (Applies to the FROM_ARCHIVE property when the HTTP protocol is used.)

HTTP_PROXY_URL

When retrieving with the WebDAV transport, this character string indicates the URL of the proxy server. (Applies to the archive transport when the HTTP protocol is used with archive specifications.)

HTTP_USER

When retrieving with the WebDAV transport, this character string indicates the name of the user to bind to the Web server. (Applies to the FROM_ARCHIVE property when the HTTP protocol is used.)

NAMESPACES

When retrieving with the WebDav transport, this character string lists one or more namespaces that you are interested in, using the syntax shown in the following example:

a="http://www.host.com/myNamespace"
A="http://www.host.com/myNamespace1"
B="http://www.host.com/myNamespace2"

QUEUE_TIMEOUT

This numeric value identifies the number of seconds for the poll timeout. By default, if this property is not specified, the RETRIEVE_PACKAGE CALL routine polls and returns immediately with the number of packages found, if any. To override this default, specify the QUEUE_TIMEOUT property so that the RETRIEVE_PACKAGE CALL routine will continue to poll for packages until at least one package is found on the queue or until the timeout occurs, whichever occurs first.

Type:	Character or Numeric
Direction:	Input

When retrieving FROM_QUEUE, this CALL routine retrieves descriptive header information for all packages that are found on the specified queue. The total number of packages found is returned. The descriptive header information for each package can be obtained by executing the PACKAGE_FIRST and PACKAGE_NEXT CALL routines.

When retrieving from the queue transport, no entries or packages are removed or deleted from the queue. Packages can be removed by calling the PACKAGE_DESTROY CALL routine.

The ARCHIVE_PATH property identifies where the archive is created. When retrieving from an archive, the name of the archive can be specified as a physical pathname, an FTP URL, or an HTTP URL.

When retrieving from a WebDAV-compliant server, the name of the archive can be specified as an FTP URL or an HTTP URL.

In the z/OS operating environment, archives can be retrieved only from UNIX System Services directories.

Example 1: Using RETRIEVE_PACKAGE to Retrieve Information for Packages on a Queue

The following example opens the queue JSMITH and retrieves the descriptive header information for all packages on that queue and the total number of packages on the queue.

plist=0;
qname = "MQSERIES://LOCAL:JSMITH";
rc=0;
total=0;
nameValue='';
CALL RETRIEVE_PACKAGE(plist, "FROM_QUEUE",
   qname, total, rc);

Example 2: Using RETRIEVE_PACKAGE to Retrieve an Archive

The following example retrieves the archive named STATUS.

plist=0;
archiveName = "/maintenance/status";
rc=0;
total=0;
CALL RETRIEVE_PACKAGE(plist, "FROM_ARCHIVE",
   archiveName, total, rc);

Example 3: Using RETRIEVE_PACKAGE to Retrieve a Package from a WebDAV Server

The following example retrieves the package from WebDAV by using the specified URL.

plist=0;
url = "http://AlphaliteAirways.host.com/~flights";
rc=0;
total=0;
property='namespaces';
ns="homePage='http://AlphaliteAirs.com/'";
CALL RETRIEVE_PACKAGE(plist, "FROM_WEBDAV",
   url, total, rc, property, ns);

Example 4: Using RETRIEVE_PACKAGE with a Queue Polling Timeout

The following example applies a queue polling timeout value of 120 seconds. The RETRIEVE routine seeks packages on the queue until at least one package is located or the 120-second timeout expires, whichever occurs first.

plist=0;
qname = "MQSERIES://LOCAL:JSMITH";
rc=0;
total=0;
nameValue='';
prop='queue_timeout';
timeout = 120;
CALL RETRIEVE_PACKAGE(plist, "FROM_QUEUE",
   qname, total, rc, prop, timeout);

Example 5: Using RETRIEVE_PACKAGE to Extract Entries from an Archive

The following example is a SAS program that extracts entries from an archive. The RETRIEVE_PACKAGE routine opens the archive file and retrieves the headers for all package entries. Subsequent RETRIEVE routines are called to retrieve the contents of the entries (in this example, data sets, catalogs, and MDDBs) and to dispose of them appropriately.

data _null_;
   length description nameValue type userSpec msg $255;
   length libname $8;
   length memname $32;
   call retrieve_package(pid,"FROM_ARCHIVE",
      "AlphaliteAir",tp,rc);
   do while (rc = 0);
      call entry_next(pid,eid,type,userSpec,
         description,nameValue,rc);
      if (rc = 0) then select (type);
         when ("DATASET")
            call retrieve_dataset(eid,libname,memname,rc);
         when ("CATALOG")
            call retrieve_catalog(eid,libname,memname,rc);
         when ("MDDB")
            call retrieve_mddb(eid,libname,memname,rc);
         otherwise;
      end;
   end;
   call package_term(pid,rc);
run;

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