PACKAGE_PUBLISH (Publish Package to E-mail)

Publishes a package using the e-mail transport

Syntax

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

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 by using the e-mail transport, specify TO_EMAIL.
Type:Character, Input
rc
specifies 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:
  • ADDRESSLIST_DATASET_LIBNAME
  • ADDRESSLIST_DATASET_MEMNAME
  • ADDRESSLIST_VARIABLE_NAME
  • APPLIED_TEXT_VIEWER_NAME
  • APPLIED_VIEWER_NAME
  • ARCHIVE_NAME
  • ARCHIVE_PATH
  • COLLECTION_URL
  • DATASET_OPTIONS
  • ENCODING
  • FROM
  • FTP_PASSWORD
  • FTP_USER
  • HTTP_PASSWORD
  • HTTP_PROXY_URL
  • HTTP_USER
  • IF_EXISTS
  • PARENT_URL
  • PROCESS_VIEWER
  • REPLYTO
  • SENDER
  • SUBJECT
  • TARGET_VIEW_MIMETYPE
  • TARGET_VIEW_NAME
  • TARGET_VIEWER_MIMETYPE
  • TARGET_VIEWER_NAME
  • TEXT_VIEWER_NAME
  • VIEWER_NAME
Type:Character, Input
address1 <, …addressN>
specifies one or more e-mail addresses to use when publishing the package.
Type:Character, Input

Optional Argument

propValue1, …propValueN
specifies a 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:
ADDRESSLIST_DATASET_LIBNAME an alternative to specifying explicit e-mail addresses, specifies a character string that indicates the name of the SAS library in which resides the data set from which an e-mail list can be extracted.
ADDRESSLIST_DATASET_MEMNAME an alternative to specifying explicit e-mail addresses, specifies a character string that indicates the name of the SAS member in which resides the data set from which an e-mail list can be extracted. The data set is fully specified by library.member.
ADDRESSLIST_VARIABLE_NAME specifies a character string that indicates the name of the variable (or column) in the data set that contains the e-mail addresses.
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.
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.
DATASET_OPTIONS specifies a character string that indicates the options to use for opening and accessing a SAS data set that contains e-mail addresses that are used to populate addressn. Specify this property as valuevalueoption1= option2= ....
ENCODING specifies a character string that indicates the text encoding to use for the message body.
FROM specifies a character string that indicates the name or e-mail address of the sender (or package publisher) of the e-mail message. This value is the name or e-mail address that the e-mail will appear to be from. 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.
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.
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.
SENDER specifies a character string that indicates the e-mail address of the sender (or package publisher) of the e-mail message. A valid e-mail address should be specified. This address will receive any bounced or undeliverable e-mail. This value is the actual e-mail address that the e-mail is sent from.
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

Details

Default Behavior

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, then 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"

Archive Path Properties

If you specify the ARCHIVE_PATH property, then 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, 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".
If you specify ARCHIVE_PATH as an FTP URL or as an HTTP URL, and need details about 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.
If you specify the PROCESS_VIEWER property (with either the VIEWER_NAME or TEXT_VIEWER_NAME 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 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, or HTTP_USER.

Viewer Properties

If you specify the VIEWER_NAME or TEXT_VIEWER_NAME property, then 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, 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.

WebDAV Properties

If you specify the COLLECTION_URL property, then 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/AlphaliteAirways/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/AlphaliteAirways/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 the 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:
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 E-mail

publishType = "TO_EMAIL";
properties='';
CALL PACKAGE_PUBLISH(packageId, publishType, rc, properties,
   "user1@alphaliteairways.com", "John Smith",
   "jsmith@alphaliteairways.com");

Example 2: Using PACKAGE_PUBLISH to Publish to E-mail with the SUBJECT Property

publishType = "TO_EMAIL";
subject = "Nightly Builds Update";
properties="SUBJECT";
Addr = "admins-l@alphaliteair03.vm.com";
CALL PACKAGE_PUBLISH(packageId, publishType,
   rc, properties, subject, Addr);

Example 3: Using PACKAGE_PUBLISH to Publish to Two E-mail Addresses with the APPLIED_VIEWER_NAME Property

The following example publishes a package to two e-mail addresses and designates the viewer to be used when formatting the e-mail message. The e-mail message will contain only content that can be rendered in a view. The rendered view is deleted after it is published.
In order to save the rendered view explicitly, you can specify the APPLIED_VIEWER_NAME property and a filename value.
publishType = "TO_EMAIL";
properties="SUBJECT, VIEWER_NAME";
subject = "Nightly Build Updates";
viewer = "filename:template.html";
Addr = "admins-l@alphaliteair03.vm.com";
CALL PACKAGE_PUBLISH(packageId, publishType,
   rc, properties, subject, viewer,
   "buildmonitor@alphaliteairways.com", Addr);

Example 4: Using PACKAGE_PUBLISH to Publish to E-mail with the ARCHIVE_PATH Property

publishType = "TO_EMAIL";
properties="ARCHIVE_PATH";
apath = "/u/users1";
Addr = "admins-l@alphaliteair05";
CALL PACKAGE_PUBLISH(packageId, publishType,
   rc, properties, apath, Addr);

Example 5: Using PACKAGE_PUBLISH to Publish a Collection URL on a WebDAV-Compliant Server to E-mail

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";
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 6: Using PACKAGE_PUBLISH to Publish to E-mail Addresses That Are in a Password-Protected SAS Data Set

The following example specifies e-mail addresses that are stored in a variable in a password-protected SAS data set.
publishType = "TO_EMAIL";
properties = "SUBJECT, ADDRESS_DATASET_LIBNAME,
   ADDRESS_DATASET_MEMNAME, ADDRESSLIST_VARIABLE_NAME,
   DATASET_OPTIONS";
subject = "Get out and Vote!";
lib = "voterreg";
mem = "northeast";
var = "emailaddr";
opt = "pw='born2run'";
CALL PACKAGE_PUBLISH(packageId, publishType, rc,
   properties, subject, lib, mem, var, opt);