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 IBM WebSphere MQ queues, use the following syntax:

MQSERIES://queueManager:queueName

MQSERIES-C://queueManager:queueName

MQSERIES specifies the server interface that is used to connect to a queue manager that is local. MQSERIES-C specifies the client interface that is used, allowing the queue manager to be local or remote.

When retrieving from SharePoint, use the value for SITE_URL.

Type:Character, Input

totalPackages: provides the total number of packages found.

Type:Numeric, Output

rc: receives a return code.

Type:Numeric, Output

Optional Arguments

properties

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

COLLECTION_NAME
CORRELATIONID
FTP_PASSWORD
FTP_USER
HTTP_PASSWORD
HTTP_PROXY_URL
HTTP_USER
LIST_NAME
NAMESPACES
QUEUE_TIMEOUT

Type:Character, 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:

COLLECTION_NAME
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.)
LIST_NAME	When retrieving with the SharePoint transport, this character string indicates a document library in the SharePoint site. SharePoint document libraries are a special type of list that is used for ordering folders and files.
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 time-out. 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 time-out occurs, whichever occurs first.

Type:Character or Numeric, Input

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 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.

Examples

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 Time-out

The following example applies a queue polling time-out value of 120 seconds. The RETRIEVE routine seeks packages on the queue until at least one package is located or the 120-second time-out 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(packageId,"FROM_ARCHIVE",
      "AlphaliteAir",tp,rc);
   do while (rc = 0);
      CALL ENTRY_NEXT(packageId,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(packageId,rc);
run;

Example 6: Using RETRIEVE_PACKAGE to Retrieve a Package from SharePoint

The following example is a SAS program that retrieves a package from SharePoint.

data _null_;
   length properties nameValue entryType userSpec filename filepath channel $ 255;
   length abstract desc msg $2048;
   abstract      = '';
   channel       = '';
   entryCount    = 0;
   entryId       = 0;
   packageId     = 0;
   rc            = 0;
   totalPackages = 0;
   packageId     = 0;
   numEntries    = 0;

   retrievalType = 'FROM_SHAREPOINT';
   siteUrl       = 'http://host/site';
   retrievalInfo = siteUrl;
   properties    = 'LIST_NAME, COLLECTION_FOLDER, HTTP_USER, HTTP_PASSWORD';
   listName      = 'Shared Documents';
   folderName    = 'File Collection';
   userName      = 'username';
   password      = 'password';

   CALL RETRIEVE_PACKAGE(packageId, retrievalType, retrievalInfo, totalpackages, rc,
                         properties, listName, folderName, userName, password);
   if rc ne 0 then do;
      msg = sysmsg();
      put msg;
      ABORT;
   end;

   properties = 'ABSTRACT';

   CALL PACKAGE_FIRST(packageId, numEntries, desc, dateTime, nameValue, channel, rc,
                      properties, abstract);
   if (rc = 0) then do;
      put "packageId: "     packageId;
      put "  numEntries: "  numEntries;
      put "  Description: " desc;
      put "  nameValue: "   nameValue;
      put "  dateTime: "    dateTime datetime21.2 " GMT";
      put "  abstract: "    abstract;
   end;
   else do;
      msg = sysmsg();
      put msg;
      ABORT;
   end;

   properties = 'FILENAME';
   do while (rc = 0);
      CALL ENTRY_NEXT(packageId, entryId, entryType, userSpec, desc, nameValue, rc,
                      properties, filename);
      if (rc = 0) then do;
         entryCount = entryCount + 1;
         put 'Entry: ' entryCount;
         put '        EntryId: '     entryId;
         put '        Type: '        entryType;
         put '        UserSpec: '    userSpec;
         put '        Description: ' desc;
         put '        nameValue: '   nameValue;

         if (entryType = 'TEXT' OR entryType = 'BINARY') then do;
            filepath = 'FILENAME: C:\Public\' || filename;
            CALL RETRIEVE_FILE(entryId, filepath, rc2);
            if (rc2 ne 0) then do;
               msg = sysmsg();
               put msg;
            end;
            else do;
               put 'File retrieved: ' filepath;
            end;
         end;
      end;
      else do;
         msg = sysmsg();
         put msg;
      end;
   end; /* do while */

   CALL PACKAGE_TERM(packageId, rc);
   if rc ne 0 then do;
      msg = sysmsg();
      put msg;
      ABORT;
   end;
run;