|
|
Publish Package Interface |
|
The PACKAGE_PUBLISH CALL routine publishes the specified package. The method of publication depends on the following types of delivery transport:
Publishes a package to an archive.
CALL PACKAGE_PUBLISH(packageId, publishType, rc, properties,< propValue1, ...propValueN>);
The ARCHIVE_NAME property identifies the name of the archive file to create. If this property is omitted, the archive transport generates a unique name by default.
The ARCHIVE_PATH property identifies where the archive is created. This property can be a physical path name, an LDAP URL, an FTP URL, or an HTTP URL.
Note: In the OS/390 operating environment, an archive can be published only to UNIX System Services directories.
How to Specify an ARCHIVE_PATH
If ARCHIVE_PATH is an LDAP URL, it should represent the sasArchivePath distinguished name. The sasArchivePath entry within the LDAP directory contains a saspath attribute that is used to create the archive.
Furthermore, if an LDAP URL is specified and the LDAP server is running secured, you must specify the LDAP_BINDDN and LDAP_BINDPW properties (or bindname and password LDAP URL extensions) in order to bind to the LDAP server.
If ARCHIVE_PATH is an HTTP URL on a secured server, you must specify the HTTP_USER and HTTP_PASSWORD properties. Specifying the HTTP_PROXY_URL property is optional.
If ARCHIVE_PATH is an FTP URL on a secured host, you must specify the FTP_USER and FTP_PASSWORD properties.
pubType = "TO_ARCHIVE"; properties='archive_path, archive_name'; path = '/u/users'; name = 'results'; CALL PACKAGE_PUBLISH(packageId, pubType, rc, properties, path, name);
apath = "ldap://pcc.host.com:389/sasarchivepathcn=HrArchive,
saschannelcn=HR,cn=saschannels,sasComponent=sasPublishSubscribe,
cn=SAS,o=Alpine Airways,c=US";
pubType = "TO_ARCHIVE";
properties='archive_path';
CALL PACKAGE_PUBLISH(packageId, pubType, rc, properties, apath);
Publishes a package using the e-mail transport.
CALL PACKAGE_PUBLISH(packageId, publishType, rc, properties, <propValue1, ...propValueN> , address1<, ...addressN>);
When publishing to e-mail, the e-mail message is sent in plain text format by default. Only inserted reference entries are published to e-mail. For details about inserting reference entries, see the INSERT_REF CALL routine.
The package description field precedes the reference value in the e-mail message. All other entries that are inserted into the package are ignored.
To override the default behavior, you can specify the ARCHIVE_PATH, COLLECTION_URL, PARENT_URL, TEXT_VIEWER_NAME, or VIEWER_NAME properties.
Note: If the mailer is not running in a Windows NT operating environment, you will be prompted for the mail profile to use when you send the e-mail message. To avoid being prompted, specify the EMAILID and EMAILPW options at SAS invocation. For example:
sas -EMAILID "Microsoft Outlook"
If you specify the ARCHIVE_PATH property, an archive is created and published as an e-mail attachment. All entries that are inserted into the package are published as an archive. If you specify a value for ARCHIVE_PATH, 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".
If you specify ARCHIVE_PATH as an LDAP URL, an FTP URL, or an HTTP URL, see How to Specify an ARCHIVE_PATH for details about archive properties.
Note: In order to create an archive under the OS/390 operating environment, the OS/390 environment must support UNIX System Services directories.
If you specify the PROCESS_VIEWER property (with either the VIEWER_NAME or TEXT_VIEWER_NAME property) along with the ARCHIVE_PATH property, 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 more information about the application of viewer properties, see Viewer Processing.
When publishing to an archive with the e-mail transport, you can specify the following archive properties: ARCHIVE_NAME, ARCHIVE_PATH, FTP_PASSWORD, FTP_USER, HTTP_PASSWORD, HTTP_PROXY_URL, HTTP_USER, LDAP_BINDDN, or LDAP_BINDPW.
If you specify the VIEWER_NAME or TEXT_VIEWER_NAME property, the viewer is used to create the e-mail message and to apply substitutions. VIEWER_NAME renders the view in HTML format. TEXT_VIEWER_NAME renders the view in text format. Only the package information that is rendered by the viewer is published.
If you specify the PROCESS_VIEWER property (with either the VIEWER_NAME or TEXT_VIEWER_NAME property) along with the ARCHIVE_PATH property, 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.
If you specify the COLLECTION_URL property, the package is published to the specified URL on a WebDAV-compliant Web server. An example of a collection URL is http://www.host.com/AlpineAirways/revenue/quarter1. The collection is named quarter1. The e-mail message that is sent to subscribers will contain a reference to the URL that is specified in the COLLECTION_URL property.
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/AlpineAirways/revenue. An example of a collection name that is automatically generated might be s9811239. The e-mail message contains a reference to the collection, which is URL that you specified in the PARENT_URL property.
The specifications of COLLECTION_URL and PARENT_URL are mutually exclusive.
When publishing to a WebDAV-compliant server with the e-mail transport, 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:
| Item Type | File Extension |
|---|---|
| CATALOG | .sac |
| DATA | .sad |
| FDB | .saf |
| MDDB | .sam |
| VIEW | .sav |
pubType = "TO_EMAIL";
properties='';
CALL PACKAGE_PUBLISH(packageId, pubType, rc, properties,
"user1@alpineairways.com", "John Smith",
"jsmith@alpineairways.com");
pubType = "TO_EMAIL"; subject = "Nightly Builds Update"; properties="SUBJECT"; Addr = "admins-l@alpineair03.vm.com"; CALL PACKAGE_PUBLISH(packageId, pubType, rc, properties, subject, Addr);
pubType = "TO_EMAIL";
properties="SUBJECT, VIEWER_NAME";
subject = "Nightly Build Updates";
viewer = "filename:template.html";
Addr = "admins-l@alpineair03.vm.com";
CALL PACKAGE_PUBLISH(packageId, pubType, rc, properties, subject, viewer,
"buildmonitor@alpineairways.com", Addr);
pubType = "TO_EMAIL"; properties="ARCHIVE_PATH"; apath = "/u/users1"; Addr = "admins-l@alpineair05"; CALL PACKAGE_PUBLISH(packageId, pubType, rc, properties, apath, Addr);
pubType = "TO_EMAIL";
properties="COLLECTION_URL, SUBJECT", "HTTP_USER", "HTTP_PASSWORD";
collurl="http://www.alpineairways/fares/discount";
subj="Announcing Best Rates Yet";
http_user="vicdamone";
http_password="myway";
Addr = "admins-l@alpineair05";
CALL PACKAGE_PUBLISH(packageId, pubType, rc, properties, collurl, subj,
http_user, http_password, Addr);
pubType = "TO_EMAIL";
properties = "SUBJECT, ADDRESS_DATASET_LIBNAME, ADDRESS_DATASET_MEMNAME,
ADDRESSLIST_VARIABLENAME, DATASET_OPTIONS";
subject = "Get out and Vote!";
lib = "voterreg";
mem = "northeast";
var = "emailaddr";
opt = "pw='born2run'";
CALL PACKAGE_PUBLISH(packageId, pubType, rc, properties, subject, lib,
mem, var, opt);
Publishes a package to one or more message queues.
CALL PACKAGE_PUBLISH(packageId, publishType, rc, properties, <propValue1, ...propValueN>, queue1<, ...queueN>);
MSMQ://queueHostMachineName\queueNameWhen publishing to MQSeries queues, use the following syntax:
MQSERIES://queueManager:queueNameor
MQSERIES-C://queueManager:queueName
When publishing to a queue, all entries in the package are published to the queue by default. To override this default, specify the ARCHIVE_PATH property, which indicates that an archive is to be created and only the archive will be published to the queue. The archive will contain all package entries.
If you specify a value for ARCHIVE_PATH, the 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".
If you specify ARCHIVE_PATH as an LDAP URL, an FTP URL, or an HTTP URL, see How to Specify ARCHIVE_PATH for details about specifying archive properties.
Note: In the OS/390 operating environment, you can publish archives only to UNIX System Services directories.
Queues that support transactional units of work are recommended. By using these types of queues, the queue transport prevents partial packages from remaining on the queue in cases where errors are encountered during package publishing. For MSMQ, this means that the queue should be transactional. For MQSeries, this means that the queue should support synchronization points.
When you specify the CORRELATIONID property, the package message uses the specified CORRELATIONID value. You can retrieve packages can be retrieved from the queue by correlation ID.
The following example publishes a package to two queues. One queue is an MQSeries queue that is named PCONE; the second queue is an MSMQ queue that is specified by the queue manager who is named JSMITH. A CORRELATIONID of 12345678901234567890 is assigned to the package to be published to both queues.
PubType = "TO_QUEUE";
FirstQ = "MQSERIES://PCONE:LOCAL";
SecondQ = "MSMQ://JSMITH:TRANSQ";
CorrValue = "12345678901234567890";
Call PACKAGE_PUBLISH(packageId, pubType, rc, "CORRELATIONID",
CorrValue, firstQ, secondQ);
The following example publishes the package to one queue and does not apply any additional queue properties:
pubType = "TO_QUEUE"; firstQ = "MQSERIES://PCONE:MYQ"; Call PACKAGE_PUBLISH(packageId, pubType, rc, '', firstQ);
The following example creates an archive and publishes it to a queue. The ARCHIVE_PATH property is specified as "tempfile". After the archive is published to the queue, the temporary, local copy is deleted automatically. The archive contains all entries that are inserted into the package.
pubType = "TO_QUEUE"; firstQ = "MQSERIES://PCONE:MYQ"; prop = "ARCHIVE_PATH"; archivePath = "tempfile"; Call PACKAGE_PUBLISH(packageId, pubType, rc, prop, archivePath, firstQ);
Publishes a package to subscribers who are associated with specified channel.
CALL PACKAGE_PUBLISH(packageId, publishType, rc, properties, < propValue1, ...propValueN>, channel);
For details about defining LDAP entries for channels and subscribers, see the documentation for SAS Integration Technologies Administrator.
Subscribers can use the SAS Subscription Manager application to subscribe to channels and to filter the packages and entries that are published to them. Name/value filters set criteria for packages and package entries. MIME-type filters set criteria for package entries that are based on file type.
The mimeType parameter is case-insensitive when the
sasFileMIMETypeInclusionFilter and the sasFileMIMETypeExclusionFilter
LDAP attributes are applied to LDAP subscribers as package entry filters.
Refer to Filtering Packages and Package Entries for details.
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 sasQueueName attribute is used as the key to enforce uniqueness. When the delivery transport is e-mail, the sasemailaddress attribute is used as the key to enforce uniqueness.
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.
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.
Subscribers can also use the sasEmailFormat LDAP attribute to indicate whether they want to receive the e-mail message in HTML format or text format. If no attribute is found when you specify the VIEWER_NAME, the message is published in HTML format by default. If the subscriber specifies text format, the viewer is notused. Instead the subscriber receives reference entries only.
Refer to Viewer Processing for more information.
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 will contain 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.
When publishing to subscribers, the ARCHIVE_PATH property indicates that an archive is to be created at the specified path and that only the archive is to be published to the subscribers. To use the channel's default archive path, you must include this property and leave the value blank.
Subscribers can use the sasArchiveReceiveBy LDAP attribute to indicate whether they want to receive the archive by value or by reference. If no attribute is specified, the default is to publish the archive by value.
For details about defining channels with the sasArchivePath attributes, see documentation for SAS Integration Technologies Administrator.
For channel subscribers who specify e-mail as the delivery transport, the created archive is included as an attachment to the e-mail message. For channel subscribers who specify a queue delivery transport, the created archive is published to the queue.
If you specify the PROCESS_VIEWER property with the ARCHIVE_PATH property, 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.
The ARCHIVE_PATH property identifies where the archive is created. This property can be a physical path name, an LDAP URL, an FTP URL, or an HTTP URL.
If you specify an LDAP URL, it should be the sasArchivePath distinguished name.
The sasArchivePath entry within the LDAP directory will contain a
saspath attribute, which is used to create the archive.
If the LDAP server is running secured, 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. In addition, if the ARCHIVE_PATH is an LDAP URL, 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 property value is blank, and the
sasArchivePathCn attribute is specified in the sasChannel
entry, an archive name is automatically generated. The archive is cataloged under the specified sasArchivePath.
If ARCHIVE_PATH is an HTTP URL on a secured server, you must specify the HTTP_USER and HTTP_PASSWORD properties. Specifying the HTTP_PROXY_URL property is optional.
If ARCHIVE_PATH is an FTP URL on a secured host, you must specify the FTP_USER and FTP_PASSWORD properties.
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 OS/390 operating environment, the OS/390 environment must support UNIX System Services directories.
If you specify the COLLECTION_URL or PARENT_URL property, the package is published as a WebDAV collection to a WebDAV-compliant Web server. The PARENT_URL property is similar to the COLLECTION_URL property except that it specifies only the location under which the new WebDAV collection is to be placed. For COLLECTION_URL, you specify the full path and an explicit collection name. For PARENT_URL, you specify only the full path and a unique name is assigned to the collection automatically.
Subscribers to channels 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 collection 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:
| Item Type | File Extension |
|---|---|
| CATALOG | .sac |
| DATA | .sad |
| FDB | .saf |
| MDDB | .sam |
| VIEW | .sav |
pubType = "TO_SUBSCRIBERS";
props='CHANNEL_STORE';
storeInfo = "LDAP://alpair02.unx.com:8010/o=Alpine Airways,c=US
????bindname=cn=John Smith%2c o=Alpine Airways%2c c=US,
password=JSmith3";
channel = 'WeeklyPayroll';
CALL PACKAGE_PUBLISH(packageId, pubType, rc, props, storeInfo, channel);
pubType = "TO_SUBSCRIBERS";
storeInfo = "LDAP://alpair02.unx.com:8010/o=Alpine Airways,c=US";
channel = 'HR';
property = "SUBJECT, CHANNEL_STORE";
subject = "Weekly HR Updates:"
CALL PACKAGE_PUBLISH(packageId, "TO_SUBSCRIBERS", rc, property, subject,
storeInfo, channel);
Publishes a package to a WebDAV-compliant server.
Publishing with a publishType of TO_WEBDAV publishes a package to a specified URL on a WebDAV-compliant 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, the package is published to the specified URL on a WebDAV-compliant Web server. An example of a collection URL is http://www.host.com/AlpineAirways/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/AlpineAirways/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 control the treatment of same-named collections already existing on the server, use the IF_EXISTS property. The character string "noreplace" in this property indicates that if the package being published contains a collection that already exists, the PUBLISH_PACKAGE call is to return immediately without affecting the contents of the existing collection. The string "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, the HTML set in the published package replaces the HTML set in the existing collection. Note: When names are generated automatically for HTML set collections, the publish code ensures that name collisions will not occur.
To announce the availability of new WebDAV collections on WebDAV-compliant servers, use a publishType of TO_SUBSCRIBERS or TO_EMAIL.
If you specify the VIEWER_NAME property with the COLLECTION_URL or PARENT_URL property, the view is rendered in HTML format. If you specify the TEXT_VIEWER_NAME with the COLLECTION_URL or PARENT_URL properties, 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 file name for the rendered view.
WebDAV publishing uses the following file extensions for each item type:
| Item Type | File Extension |
|---|---|
| CATALOG | .sac |
| DATA | .sad |
| FDB | .saf |
| MDDB | .sam |
| VIEW | .sav |
If a namespace is associated with the name portion of a name/value pair, the name can also include a colon (:). For details about the NAMESPACE property, see PACKAGE_BEGIN.
For details 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:
rc = 0; pubType = "TO_WEBDAV"; subject = "Nightly Maintenance Report"; properties="COLLECTION_URL"; cUrl = "http://www.alpair.web/NightlyMaintReport"; CALL PACKAGE_PUBLISH(packageId, pubType, rc, properties, cUrl);
rc = 0; pubType = "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 = "replace"; user = "JohnSmith"; password = "secret"; CALL PACKAGE_PUBLISH(packageId, pubType, rc, properties, cUrl, pUrl, exists, user, password);
The following example uses the e-mail transport to publish a collection URL on a WebDAV-compliant server. The HTTP userid 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.
pubType = "TO_EMAIL";
properties="COLLECTION_URL, SUBJECT";
collurl="http://www.alpineairways/fares/discount.html";
subj="Announcing Best Rates Yet";
http_user="vicdamone";
http_password="myway";
Addr = "admins-l@alpineair05";
CALL PACKAGE_PUBLISH(packageId, pubType, rc, properties, collurl, subj,
http_user, http_password, Addr);
Note: The FROM field is valid only with the SMTP e-mail interface.
A text viewer template might be necessary if the destination e-mail program does not support the HTML MIME type. (Applies to the following transports: e-mail, subscriber, WebDAV.)
See Viewer Processing for more information.
|
|
Publish Package Interface |
|