RETRIEVE_PACKAGE

This CALL routine retrieves descriptive header information for all packages.

Syntax

CALL RETRIEVE_PACKAGE(pkgListId, retrievalType, retrievalInfo, totalPackages, rc<, properties, propValue1, propValueN>);

pkgListId

Numeric, output.
Identifies the list of packages.

retrievalType

Character, input.
Specifies the transport to use when retrieving a package. Valid values include the following:

• FROM_QUEUE
• FROM_ARCHIVE
• FROM_WEBDAV

retrievalInfo

Character, input.
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

totalPackages

Numeric, output.
Provides the total number of packages found.

rc

Numeric, output.
Receives a return code.

properties

Character, input.
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
• LDAP_BINDDN
• LDAP_BINDPW
• NAMESPACES
• QUEUE_TIMEOUT

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

Character string specifies retrieval of only those packages that possess 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.)

LDAP_BINDDN

Character string indicates the distinguished name used to bind to the LDAP server. This property is necessary only when an archive is retrieved using an LDAP URL.

LDAP_BINDPW

Character string indicates the password used to bind to the LDAP server. This property is necessary only when retrieving an archive using an LDAP URL.

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

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.

Details

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 may 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 path name, an LDAP URL, an FTP URL, or an HTTP URL. The archive entry in LDAP contains attributes that identify the name of the archive to retrieve. Refer to SAS Integration Technologies Administrator for details on the archive LDAP entries.

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.

Examples

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);

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);

The following example retrieves the package from WebDAV 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);

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);

The following example uses an LDAP URL to retrieve the archive. The LDAP URL is the sasArchive distinguished name.

   plist=0;
   archiveName = 
      "ldap://pcc.host.com:389/sasarchivecn=weekOne,
      saschannelcn=HR,cn=saschannels,
      sasComponent=sasPublishSubscribe,
      cn=SAS,o=Alphalite Airways,c=US";
   rc=0;
   total=0;
   CALL RETRIEVE_PACKAGE(plist, "FROM_ARCHIVE", 
      archiveName, total, rc);

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;