PACKAGE_PUBLISH (Publish Package to a WebDAV-Compliant Server)

Publishes a package to a WebDAV-compliant server

Syntax

CALL PACKAGE_PUBLISH(packageId, publishType, rc, properties,
<propValue1, ...propValueN> );

Required Arguments

packageID
identifies the package that is to be published.
Type:Numeric, Input
publishType
indicates how to publish the package. To publish the package using the WebDAV transport, specify a publishType of TO_WEBDAV.
Type:Character, Input
rc
receives a return code.
Type:Numeric, Output
properties
identifies a comma-separated list of optional property names. Specify any of the following property names, or specify '' to indicate that no properties are to be applied:
  • APPLIED_TEXT_VIEWER_NAME
  • APPLIED_VIEWER_NAME
  • ARCHIVE_FULLPATH
  • ARCHIVE_NAME
  • ARCHIVE_PATH
  • COLLECTION_URL
  • GENERATED_NAME
  • HTTP_PASSWORD
  • HTTP_PROXY_URL
  • HTTP_TOKENAUTH
  • HTTP_USER
  • IF_EXISTS
  • PARENT_URL
  • TARGET_VIEW_MIMETYPE
  • TARGET_VIEW_NAME
  • TARGET_VIEWER_MIMETYPE
  • TARGET_VIEWER_NAME
  • TEXT_VIEWER_NAME
  • VIEWER_NAME
Type:Character, Input

Optional Argument

propValue1, …propValueN
specifies one value for each specified property name. The order of the property values must match the order of the property names in the properties parameter. Valid property values are defined as follows:
APPLIED_TEXT_VIEWER_NAME specifies a character string that names the rendered package view, which results from the application of the text viewer template. To specify the name of the rendered package view, use either FILEREF:SAS_fileref or FILENAME:external_filename. This property is valid only when the TEXT_VIEWER_NAME property is also specified. By default, the rendered view is created as a temporary file. This property overrides the default, causing the rendered view to be saved permanently to a file.
APPLIED_VIEWER_NAME specifies a character string that indicates the name of the rendered package view, which results from the application of the HTML viewer template. To specify the name of the rendered package view, use either FILEREF:SAS_fileref or FILENAME:external_filename. This property is valid only when the VIEWER_NAME property is also specified. By default, the rendered view is created as a temporary file. This property overrides the default, causing the rendered view to be saved permanently to a file.
ARCHIVE_FULLPATH returns the complete URL path of the published archive on the server. The URL path includes the name of the archive, as specified by ARCHIVE_NAME or the generated name if ARCHIVE_NAME is not specified. This output property is returned only if ARCHIVE_PATH is specified.
ARCHIVE_NAME specifies a character string that indicates the name of the archive file.
ARCHIVE_PATH specifies a character string that indicates the path where the archive should be created.
COLLECTION_URL specifies a character string that indicates the URL in which the WebDAV collection is placed. You assign an explicit filename to the collection. Note that when you use COLLECTION_URL, the default behavior is to replace the existing collection at that location.
GENERATED_NAME returns the name of the package, whether this value was generated by SAS or specified by another property. This property is an output property. If the package is published with a PARENT_URL, and ARCHIVE_PATH is not specified, then the package is published as a folder that contains the contents of the package and not as a .spk file. In this case, the return value for GENERATED_NAME will not be the name of the archive but the name of the package. For SharePoint, this is a folder name.
HTTP_PASSWORD indicates the password that is needed to bind to the Web server on which the package is published. Specify this property only when the Web server is secured.
HTTP_PROXY_URL indicates the URL of the proxy server.
HTTP_TOKENAUTH enables token authentication to a SAS Content Server. Value must be set to TRUE, FALSE, YES, or NO. Do not specify values for HTTP_USER or HTTP_PASSWORD if you are using this property.
HTTP_USER indicates the user ID that is needed to bind to the Web server on which the package is published. Specify this property only when the Web server is secured.
IF_EXISTS specifies one of the following character strings. Use the IF_EXISTS property to control the treatment of same-named collections already existing on the server. "NOREPLACE" indicates that if the package being published contains a collection that already exists on the server, the PUBLISH_PACKAGE call is to return immediately without affecting the contents of the existing collection. "UPDATE" indicates that if the collection already exists on the server, the PUBLISH_PACKAGE call is to update the existing collection by replacing like-named entities and adding newly named entities. If "UPDATE" is specified and both the package to publish and the existing collection have an HTML set (created with INSERT_HTML) with the same NESTED_NAME, then the HTML set in the published package replaces the HTML set in the existing collection. "UPDATEANY" is identical to "UPDATE" except that the PUBLISH_PACKAGE CALL routine can be used to update a collection that SAS did not create. A consequence of using "UPDATEANY" is that SAS will be unable to retrieve the published package. Note that when names are generated automatically for HTML set collections, the publish code ensures that name collisions will not occur.
PARENT_URL specifies a character string that indicates the URL under which the WebDAV collection is placed. The collection is automatically assigned a unique name.
TARGET_VIEW_MIMETYPE specifies a character string that indicates the MIME type of the rendered view for delivery to a WebDAV-compliant server. The target view MIME type overrides the default view MIME type, which is automatically inferred from the viewer. Typical MIME types are HTML (.htm) and plain text (.txt) files. If this field remains blank, then the viewer filename extension is used to locate the MIME type in the appropriate registry. Windows hosts use the Windows Registry; other hosts use the SAS Registry.
TARGET_VIEW_NAME specifies a character string that indicates the name of the rendered view for delivery to a WebDAV-compliant server. The specified target view name overrides the default name, which is index.html.
TEXT_VIEWER_NAME specifies a character string that indicates the name of a text viewer template that formats package content for viewing in e-mail by using either FILEREF:SAS_fileref or FILENAME:external_filename. A text viewer template might be necessary if the destination e-mail program does not support the HTML MIME type.
VIEWER_NAME specifies a character string that indicates the name of the HTML viewer template to be applied when publishing e-mail by using either FILEREF:SAS_fileref or FILENAME:external_filename.
Type:Character or Numeric, Input or Output

Details

Default Behavior

Publishing with a publishType of TO_WEBDAV publishes a package to a specified URL on a WebDAV-compliant server. Starting with SAS 9.2, the HTTPS protocol is supported when publishing to a WebDAV server. WebDAV servers enable distributed authoring and versioning, which enables collaborative development of Web files on remote servers.
The WebDAV transport stores package entries as members of a collection.
If you specify the COLLECTION_URL property, then the package is published to the specified URL on a WebDAV-compliant Web server. When you use COLLECTION_URL, the default behavior is to replace the existing collection and its nested directories at that location. If you do not want to replace an existing collection and its nested directories, then you must use the IF_EXISTS property. An example of a collection URL is
http://www.host.com/AlphaliteAirways/revenue/quarter1
The collection is named quarter1.
The PARENT_URL property is similar to the COLLECTION_URL property except that it specifies the location under which the new WebDAV collection is to be placed. The PUBLISH_PACKAGE CALL routine generates a unique name for the new collection. The unique name is limited to eight characters with the first character as an s. An example of a parent URL directory location is http://www.host.com/AlphaliteAirways/revenue. An example of a collection name that is automatically generated might be s9811239.
The specifications of the COLLECTION_URL property and the PARENT_URL property are mutually exclusive.
To announce the availability of new WebDAV collections on WebDAV-compliant servers, use a publishType of TO_SUBSCRIBERS or TO_EMAIL.
WebDAV publishing uses the following file extensions for each item type:
File Extensions for Item Types
Item Type
File Extension
ARCHIVE
.spk
CATALOG
.sac
COMMA-SEPARATED VALUES
.csv
DATA
.sad
MDDB
.sam
REFERENCE
.ref
VIEW
.sav

Viewer Properties

If you specify the VIEWER_NAME property with the COLLECTION_URL or PARENT_URL property, then the view is rendered in HTML format. If you specify the TEXT_VIEWER_NAME with the COLLECTION_URL or PARENT_URL properties, then the view is rendered in text format.
The specified viewer is used to create a rendered view that is named index.html. To override the default name that is assigned to the rendered view, use the APPLIED_VIEWER_NAME or APPLIED_TEXT_VIEWER_NAME, as appropriate, to specify a filename for the rendered view.

Archive Path Properties

If you specify the ARCHIVE_PATH property, then an archive is created and published as a binary package on a WEBDAV-compliant server. All entries that are inserted into the package are published as an archive. If you specify a value for ARCHIVE_PATH, then the created archive is stored at the designated location. To create a temporary archive that is deleted after the package is published, specify an ARCHIVE_PATH value of "" or "tempfile".
For more details about how to use the archive properties, see PACKAGE_PUBLISH (Publish Package to Archive).
Note: In order to create an archive under the z/OS operating environment, the z/OS environment must support UNIX System Services directories.
When publishing a binary package with the WEBDAV transport, you can specify the following archive properties: ARCHIVE_NAME, ARCHIVE_PATH, or ARCHIVE_FULLPATH.

Applying a Name/Value Pair to a Package and a Package Item

When publishing to a WebDAV-compliant server, optional name/value pairs are transmitted to the WebDAV server in XML format. XML format requires that the name portion of the name/value pair specification follow these conventions:
  • It must begin with an alphabetic character or an underscore.
  • It can contain only alphabetic characters, numeric characters, and these special characters: . (period), - (hyphen), and _ (underscore).
If a namespace is associated with the name portion of a name/value pair, then the name can also include a colon (:). Name/value pairs not explicitly associated with a namespace might not be retained by the WebDAV server. For details about the NAMESPACE property or about specifying the nameValue parameter for an entire package, see PACKAGE_BEGIN.
For details about specifying the nameValue parameter for a single package item, see the applicable INSERT_item CALL routine, where item can be any of the following:

Examples

Example 1: Using PACKAGE_PUBLISH to Publish to a WebDAV Server

The following example uses the HTTPS protocol when publishing to the WebDAV server:
rc = 0;
publishType = "TO_WEBDAV";
http_user="vicdamone”;
http_password=”myway”;
properties="COLLECTION_URL, http_user, http_password";
cUrl = "https://www.alpair.web/NightlyMaintReport";
CALL PACKAGE_PUBLISH(packageId, publishType,
   rc, properties, cUrl, http_user, http_password);

Example 2: Using PACKAGE_PUBLISH to Publish to a Specified Proxy Server

The following example publishes a package to a URL via the specified proxy server by using the specified credentials:
rc = 0;
publishType = "TO_WEBDAV";
properties="COLLECTION_URL,HTTP_PROXY_URL,
   IF_EXISTS,HTTP_USER,HTTP_PASSWORD";
cUrl = "http://www.alpair.secureweb/NightlyMaintReport";
pUrl = "http://www.alpair.proxy:8000/";
exists = "update";
user = "JohnSmith";
password = "secret";
CALL PACKAGE_PUBLISH(packageId, publishType, rc, properties,
   cUrl, pUrl, exists, user, password);

Example 3: Using PACKAGE_PUBLISH to Publish a Collection URL on a WebDAV-Compliant Server to a WebDAV Server

The following example uses the e-mail transport to publish a collection URL on a WebDAV-compliant server. The HTTP user ID and password enable the publisher to bind to the secured HTTP server. All e-mail recipients who are members of the mail list receive the e-mail announcement that the best rates are accessible at the specified URL.
publishType = "TO_EMAIL";
properties="COLLECTION_URL, SUBJECT,
   HTTP_USER, HTTP_PASSWORD";
collurl="http://www.alphaliteairways/fares/discount.html";
subj="Announcing Best Rates Yet";
http_user="vicdamone";
http_password="myway";
Addr = "admins-l@alphaliteair05";
CALL PACKAGE_PUBLISH(packageId, publishType, rc, properties,
   collurl, subj, http_user, http_password, Addr);

Example 4: Using PACKAGE_PUBLISH to Publish to a WebDAV Server with the ARCHIVE_PATH Property

The following example uses the ARCHIVE_PATH property to publish a binary package to the WebDAV-compliant server. The archive path is specified as "tempfile" so that the locally created archive file will be deleted once it has been published to the WebDAV server.
publishType = "TO_WEBDAV";
properties="COLLECTION_URL, ARCHIVE_PATH";
cUrl = "http://www.alpair.secureweb/Reports";
apath = "tempfile";
CALL PACKAGE_PUBLISH(packageId, publishType, rc,
   properties, cUrl, apath);