Publish to Subscribers

Publishes a package to subscribers who are associated with specified channel.

Syntax

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

packageID

Numeric, input.
Identifies the package that is to be published.

publishType

Character, input.
Indicates how to publish the package. To publish a package to the subscribers of a channel, specify a publishType value of TO_SUBSCRIBERS.

rc

Numeric, output.
Receives a return code.

properties

Character, input.
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
• FROM
• FTP_PASSWORD
• FTP_USER
• HTTP_PASSWORD
• HTTP_PROXY_URL
• HTTP_USER
• IF_EXISTS
• LDAP_BINDDN
• LDAP_BINDPW
• METAPASS
• METAUSER
• PARENT_URL
• PROCESS_VIEWER
• REPLYTO
• SUBJECT
• TARGET_VIEW_NAME
• TARGET_VIEW_MIMETYPE
• TEXT_VIEWER_NAME
• UUID
• VIEWER_NAME

propValue1, ...propValueN

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

channel

Character, input.
specifies the name of the channel as it is defined in the repository. The channel can be defined in an LDAP repository or in a SAS Metadata Repository. The channel contains a list of subscribers to whom the package will be published.

Details

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.

Channel and subscriber metadata can be defined in an LDAP repository or in a SAS Metadata Repository. If defining publishing metadata in LDAP, the SAS Integration Technologies Administrator can be used to define channels and subscribers and the SAS Subscription Manager can be used to manage subscribers. If defining the publishing metadata in a SAS Metadata Repository, the SAS Management Console's Publishing Framework plug-in can be used to configure channels and subscribers. All of these tools allow you to define/manage channels and subscribers, including the ability for subscribers to define filters that determine what packages are published to them. Refer to Filtering Packages and Package Entries for details on filters.

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.

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.

See the INSERT_REF CALL routine for details.

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, the e-mail message is published in HTML format. If you specify TEXT_VIEWER_NAME, 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, the viewer is not used and the subscriber receives reference entries only. Refer to Viewer Processing for more information about the viewer facility.

The VIEWER_NAME and TEXT_VIEWER_NAME properties override the default behavior for WebDAV subscribers as well. If you specify VIEWER_NAME, the view is rendered in HTML format. If you specify TEXT_VIEWER_NAME, 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 file name 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, 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 file name 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 path name, an LDAP URL, 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, 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. Refer to the SAS Integration Technologies Administrator documentation for details on how to define a channel's default archive path in LDAP. Refer to the help in the Publishing Framework plug-in within SAS Management Console for details on how to define a channel's default archive in a SAS Metadata Repository.

If the ARCHIVE_PATH property is specified as an LDAP URL, then the URL identifies the sasArchivePath entry within the LDAP repository. This archive path entry identifies what path is to be used when creating the archive. If the LDAP server is running secured, then you must specify the LDAP_BINDDN and LDAP_BINDPW properties (or bindname and password LDAP URL extensions) in order to provide the information that is needed to bind to the LDAP server. If the ARCHIVE_PATH property is specified as an LDAP URL, then the created archive is cataloged in LDAP as a sasArchive entry. The sasArchive entry is a child of the specified sasArchivePath entry.

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

Examples

Example 1

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/reposname=MyRepos";
   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

The following example publishes the specified package to all subscribers of the WeeklyPayroll channel. The LDAP server on ALPAIR02 will be searched for the stored channel and subscriber information. The LDAP server is using port 8010, and the base of 'o=Alphalite Airways, c=US' is to be used during the search. If the bindname contains commas or question marks, you must replace them with a percent sign followed by their ASCII hexadecimal values. This example replaces the commas in the bindname field with the hexadecimal value of %2c.

   pubType = "TO_SUBSCRIBERS";
   props='CHANNEL_STORE';
   storeInfo = 
      "LDAP://alpair02.sys.com:8010/o=Alphalite Airways,c=US
      ????bindname=cn=John Smith%2c o=Alphalite Airways%2c c=US, 
      password=JSmith3";
   channel = 'WeeklyPayroll';
   CALL PACKAGE_PUBLISH(packageId, pubType, 
      rc, props, storeInfo, channel);

Example 3

The following 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 = 
      "LDAP://alpair02.sys.com:8010/o=Alphalite Airways,c=US";
   channel = 'HR';
   property = "SUBJECT, CHANNEL_STORE";
   subject = "Weekly HR Updates:"
   CALL PACKAGE_PUBLISH(packageId, "TO_SUBSCRIBERS", 
      rc, property, subject, storeInfo, channel);