PACKAGE_PUBLISH (Publish Package to Subscribers)

Arguments

packageID

identifies the package that is to be published.

Type:	Numeric
Direction:	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
Direction:	Input

rc

receives a return code.

Type:	Numeric
Direction:	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_NAME

• TARGET_VIEW_MIMETYPE

• TEXT_VIEWER_NAME

• VIEWER_NAME

For more information about these properties, see Transport Properties.

Type:	Character
Direction:	Input

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.

Type:	Character or Numeric
Direction:	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
Direction:	Input

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 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 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 on 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:

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(pid, "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.

pubType = "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 © 2008 by SAS Institute Inc., Cary, NC, USA. All rights reserved.