PACKAGE_PUBLISH (Publish Package to Subscribers)

Publishes a package to subscribers who are associated with specified channel
Syntax
Details
Overview of Publishing to a Channel
Default Properties
Viewer Properties
Archive Path Property
WebDAV Properties
Examples
Example 1: Using PACKAGE_PUBLISH to Publish to Subscribers
Example 2: Using PACKAGE_PUBLISH to Publish to Subscribers with the Subject Property

Syntax

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

Required Arguments

packageID
identifies the package that is to be published.
Type:Numeric, Input
publishType
indicates how to publish the package. To publish a package to the subscribers of a channel, specify a publishType value of TO_SUBSCRIBERS.
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_NAME
  • ARCHIVE_PATH
  • CHANNEL_STORE
  • COLLECTION_URL
  • CORRELATIONID
  • ENCODING
  • FOLDER_PATH
  • FROM
  • FTP_PASSWORD
  • FTP_USER
  • GENERATED_NAME
  • HTTP_PASSWORD
  • HTTP_PROXY_URL
  • HTTP_USER
  • IF_EXISTS
  • METAPASS
  • METAUSER
  • PARENT_URL
  • PROCESS_VIEWER
  • REPLYTO
  • SUBJECT
  • TARGET_VIEW_MIMETYPE
  • TARGET_VIEW_NAME
  • TARGET_VIEWER_MIMETYPE
  • TARGET_VIEWER_NAME
  • TEXT_VIEWER_NAME
  • VIEWER_NAME
Type:Character, Input
channel
specifies the name of the channel as it is defined in the SAS Metadata Repository. The channel contains a list of subscribers to whom the package will be published.
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 the package for viewing in e-mail. 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 the package for viewing in e-mail. 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_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.
CHANNEL_STORE specifies a character string that indicates the SAS Metadata Repository containing the channel and subscriber metadata. If channel definitions and subscriber definitions are maintained in a SAS Metadata Repository, then the syntax for the CHANNEL_STORE property is as follows: SAS-OMA://hostname[:portreposname=repositoryName; The hostname is the name of SAS Metadata Server that contains channel information. HOSTNAME must be a DNS name or IP address of a host that is running a SAS Metadata Server. The port is the TCP port of the SAS Metadata Server. If no port is specified, then 8561 is used as a default. The reposname is the name of the repository.
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.
CORRELATIONID specifies a binary character string correlator that is used on the package header message.
ENCODING specifies a character string that indicates the text encoding to use for the message body.
FOLDER_PATH specifies the folder path for the channel of interest. This value is used to search for channels with specific names that exist in specific folder locations. When a user defines a channel via SAS Management Console, all channels by default exist in the /Channels folder. SAS Management Console allows the user to define multiple folders and subfolders. All FOLDER_PATH properties must start with /Channels and then can identify subfolders if necessary. For example, a channel named "Sales" might be defined in two different folders: /Channels/Reports/US/ or /Channels/Reports/Europe/
FROM specifies a character string that indicates the sender (or package publisher) of the e-mail message. Note that the FROM field is valid only with the SMTP e-mail interface.
FTP_PASSWORD indicates the password that is needed to log on to the remote host at which the archive will be stored. Specify this property only when the remote host is secured.
FTP_USER indicates the user ID that is needed to log on to the remote host at which the archive will be stored. Specify this property only when the remote host is secured.
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_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.
METAPASS specifies the password to use when binding to the SAS Metadata Server. If the METAPASS property is not specified on the PACKAGE_PUBLISH CALL routine, then the METAPASS system option, if set, will be used when binding to the SAS Metadata Server.
METAUSER specifies the user name to use when binding to the SAS Metadata Server. If the METAUSER property is not specified on the PACKAGE_PUBLISH CALL routine, then the METAUSER system option, if set, will be used when binding to the SAS Metadata Server.
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.
PROCESS_VIEWER specifies a character string of "yes" to indicate that the rendered view will be delivered in e-mail. If you specify the PROCESS_VIEWER property with the ARCHIVE_PATH property, then the archive is created but is not sent as an attachment in e-mail. Instead, viewer processing occurs and the rendered view is sent in e-mail.
REPLYTO specifies a character string that indicates the designated e-mail address to which package recipients might respond. Note that the REPLYTO field is valid only with the SMTP e-mail interface.
SUBJECT specifies a character string that provides the subject line for the e-mail message.
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.
TARGET_VIEWER_MIMETYPE see TARGET_VIEW_MIMETYPE.
TARGET_VIEWER_NAME see TARGET_VIEW_NAME.
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

Overview of Publishing to a Channel

When a package is published to a channel, the package is published to each subscriber of the channel. Each subscriber's entry contains an attribute that specifies the publishing transport method: e-mail, message queue, WebDAV-Compliant server, or none.
You can use the Publishing Framework plug-in for SAS Management Console to define and manage channels and subscribers. This plug-in also enables subscribers to define filters that determine what packages are published to them. For more information about filters, see Filtering Packages and Package Entries.
When publishing to subscribers, the PACKAGE_PUBLISH CALL routine ensures that the package is published to each subscriber only once, thus eliminating any duplication. When the delivery transport is a message queue, the queue name is used as the key to enforce uniqueness. When the delivery transport is WebDAV, the collection URL is used as the key to enforce uniqueness. A parent URL is always unique because the WebDAV transport always creates a unique collection name for parent URLs. When the delivery transport is e-mail, the subscriber's e-mail address is used as the key to enforce uniqueness.
In order to publish to a channel, the publisher must have Write permission. For information about permissions by task for working with publishing channels, see SAS Intelligence Platform: Security Administration Guide.
Note: You can use the package cleanup utility to delete packages that have been published to a channel. This utility is part of the Web Infrastructure Platform. For more information, see the Javadoc.

Default Properties

For channel subscribers who specify an e-mail delivery transport, the default action is to publish the e-mail message in plain text format. Only inserted references are published to the e-mail subscriber. For details, see the INSERT_REF CALL routine.
The package description field precedes the reference value in the e-mail message. All other inserted entries are ignored. For channel subscribers who specify a queue delivery transport, the default action is to publish all inserted entries to the queue.

Viewer Properties

To override the default e-mail behavior, you can specify the VIEWER_NAME or TEXT_VIEWER_NAME property on the PACKAGE_PUBLISH CALL routine. The specified viewer is used to create the content of the e-mail message and to apply substitutions. If you specify VIEWER_NAME, then the e-mail message is published in HTML format. If you specify TEXT_VIEWER_NAME, then the e-mail message is published in text format. Only the package information that is rendered by the viewer is published.
E-mail subscribers can configure the format in which they want to receive the e-mail, either in HTML or text format. The default behavior is that the message is published in HTML format. If the e-mail subscriber specifies text format, then the viewer is not used, and the subscriber receives reference entries only. For more information about the viewer facility, see the chapter about viewer processing.
The VIEWER_NAME and TEXT_VIEWER_NAME properties override the default behavior for WebDAV subscribers as well. If you specify VIEWER_NAME, then the view is rendered in HTML format. If you specify TEXT_VIEWER_NAME, 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 the rendered view, use the APPLIED_VIEWER_NAME or APPLIED_TEXT_VIEWER_NAME, as appropriate, to specify a filename for the rendered view.
The VIEWER_NAME and TEXT_VIEWER_NAME properties are ignored by the queue and archive transports.
If you specify the VIEWER_NAME or TEXT_VIEWER_NAME property with the COLLECTION_URL or PARENT_URL property, then the e-mail message contains a reference to a URL. 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 TARGET_VIEW_NAME or TARGET_VIEW_MIMETYPE, as appropriate, to specify a filename for the rendered view. The package is published to a WebDAV-compliant server. For channel subscribers who specify an e-mail delivery transport, the default action is to notify subscribers of the URL of the published package. For channel subscribers who specify a message queue delivery transport, no notification is given to indicate the package's availability on the Web.

Archive Path Property

When publishing to subscribers, the ARCHIVE_PATH property indicates that the package is to be persisted to an archive using the specified archive path. The ARCHIVE_PATH property identifies where the archive is to be persisted. This property can be a physical pathname, an FTP URL, or an HTTP URL. The channel metadata can be defined with a default persistent store. A persistent store identifies a default transport that is used to persist the package before publishing to the channel subscribers. The persistent store can be defined as a default archive path. If you specify a blank value for the ARCHIVE_PATH property, then the channel's default archive path is used to determine where the archive is to be persisted.
For channel subscribers who specify e-mail as the delivery transport, the created archive is included as an attachment to the e-mail message. If you specify the PROCESS_VIEWER property along with the ARCHIVE_PATH property, then the archive is created but is not sent as an attachment in e-mail. Instead, viewer processing occurs and the rendered view is sent in e-mail. For channel subscribers who specify a queue delivery transport, the created archive is published to the queue. For channel subscribers who specify a WebDAV delivery transport, the archive is published as a binary package to the WebDAV server.
If the ARCHIVE_PATH property is specified with a blank value, then the channel's default archive path metadata is used to determine where the archive is to be persisted. The name of the archive is automatically generated and the archive metadata is then cataloged in the channel metadata. For details about how to define a channel's default archive, see the help in the Publishing Framework plug-in for SAS Management Console.
If the ARCHIVE_PATH is an HTTP URL, then the URL identifies the HTTP server to use when persisting the archive. If it is a secured server, then you must specify the HTTP_USER and HTTP_PASSWORD properties. Specifying the HTTP_PROXY_URL property is optional. If the ARCHIVE_PATH is an FTP URL, then the URL identifies the FTP server to use when persisting the archive. If it is a secured host, then you must specify the FTP_USER and FTP_PASSWORD properties.
Note: If you specify both the ARCHIVE_PATH and either the VIEWER_NAME or TEXT_VIEWER_NAME properties, then the viewer property is ignored.
Note: In order to create an archive under the z/OS operating environment, the z/OS environment must support UNIX System Services directories.

WebDAV Properties

The channel metadata can be defined with a default persistent store. A persistent store identifies a default transport that is used to persist the package before publishing to the channel subscribers. The persistent store can be defined as a default WebDAV server.
If the COLLECTION_URL or PARENT_URL property value is blank, then the package is published to the default WebDAV server configured in the channel metadata. If you specify a non-blank COLLECTION_URL or PARENT_URL property value, then the specified URL is used as the persisted location. When a non-blank value is specified for COLLECTION_URL, the URL identifies the full path and the explicit collection name. When a non-blank value is specified for PARENT_URL, the URL identifies the full path and a unique name is assigned to the collection automatically.
Channel subscribers who specify an e-mail delivery transport are notified about the availability of the new collection. The e-mail message contains a reference to the value of the COLLECTION_URL or PARENT_URL property, which specifies the URL to which the package is published. For channel subscribers who specify a message queue delivery transport, no notification is given to announce the collection's availability.
The COLLECTION_URL (or PARENT_URL) property and the ARCHIVE_PATH property are mutually exclusive.
When publishing to a WebDAV-compliant server with the COLLECTION_URL or PARENT_URL properties, you can specify the following WebDAV properties: HTTP_PASSWORD, HTTP_PROXY_URL, HTTP_USER, IF_EXISTS, TARGET_VIEW_MIMETYPE, TARGET_VIEW_NAME, and VIEWER_NAME (or TEXT_VIEWER_NAME).
WebDAV publishing uses the following file extensions for each item type:
File Extensions for Item Types
Item Type
File Extension
CATALOG
.sac
DATA
.sad
MDDB
.sam
REFERENCE
.ref
VIEW
.sav

Examples

Example 1: Using PACKAGE_PUBLISH to Publish to Subscribers

The following example publishes the specified package to all subscribers of the Report channel. The SAS Metadata Server on ALPAIR03 is searched for the stored channel and subscriber information. The SAS Metadata Server is using port 4059 and the repository to use is MyRepos. 
channelStore =
   "SAS-OMA://alpair03.sys.com:4059";
channelName = "Report";
prop = "channel_store,metauser,metapass";
user = "myUserName";
password = "myPassword";
CALL PACKAGE_PUBLISH(packageId, "TO_SUBSCRIBERS", rc, prop,
   channelStore, user, password, channelName);

Example 2: Using PACKAGE_PUBLISH to Publish to Subscribers with the Subject Property

The following example publishes the package to all subscribers of the HR channel. The subject property is specified so that all e-mail subscribers will receive the message with the specified subject. 
publishType = "TO_SUBSCRIBERS";
storeInfo =
   "SAS-OMA://alpair03.sys.com:8561";
channel = 'HR';
property = "SUBJECT, CHANNEL_STORE, METAUSER, METAPASS";
subject = "Weekly HR Updates:"
user = "myUserName";
password = "myPassword";
CALL PACKAGE_PUBLISH(packageId, "TO_SUBSCRIBERS",
   rc, property, subject, storeInfo, user, password, channel);
Copyright © SAS Institute Inc. All rights reserved.