RETRIEVE_HTML

Retrieves an HTML entry from a package.

Syntax

CALL RETRIEVE_HTML(entryId, path, body, bodyUrl, frame, frameUrl, contents, contentsUrl, pages, pagesUrl, rc<, properties, propValue1, ...propValueN>);

entryId

Numeric, input.
Identifies the HTML entry.

path

Character, input.
Specifies the full designation of the location that will receive the retrieved files.

body

Character, output.
Returns the name of the HTML body file.

bodyUrl

Character, output.
Returns the URL of the HTML body file.

frame

Character, output.
Returns the name of the HTML frame file.

frameUrl

Character, output.
Returns the URL of the HTML frame file.

contents

Character, output.
Returns the name of the HTML contents file.

contentsUrl

Character, output.
Returns the URL of the HTML contents file.

pages

Character, output.
Returns the name of the HTML page file.

pagesUrl

Character, output.
Returns the URL of the HTML page file.

rc

Numeric, output.
Receives a return code.

properties

Character, input.
Identifies a comma-separated list of optional property names. Valid property names are as follows:

• ENCODING
• BODY_TOTAL
• FILE_TOTAL
• COMPANION_TOTAL

propValue1, ...propValueN

Character/numeric, input/output.
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:

ENCODING

Input character string indicates the target encoding for the retrieved HTML file. An example of a target encoding value is ISO-8859-1. Refer to Publish/Retrieve Encoding Behavior for further information.

BODY_TOTAL

Numeric output parameter returns the total number of HTML body files published as part of this set.

FILE_TOTAL

Numeric output parameter returns the total number of all HTML files published as part of this set. This includes all body, page, contents, frame, and additional HTML files and companion files.

COMPANION_TOTAL

Numeric output parameter returns the total number of extraneous HTML files that were published as part of this set.

Details

The ODS entry may contain any combination of the following: ODS HTML file, contents file, pages file, or frame file.

The publisher can choose to publish any combination of the HTML files. To indicate those files that were not published as part of this set, the output parameter that contains the created file name will be updated to "". For example, if only the body was published, then the page, contents, and frame parameters will be returned as "".

The pages, pagesUrl, body, bodyUrl, frame, frameUrl, contents, and contentsUrl parameters are character variables that are updated by the CALL routine. Because they are updated, they must be initialized with a length large enough to contain the name of the returned filename or URL. If the length of the character variable is less than the length of the returned filename or URL, the filename or URL will be truncated and a warning will be issued. When calling the RETRIEVE_HTML CALL routine from within the data step, use the LENGTH statement to define the length of the character variable. When calling RETRIEVE_HTML from within a macro, initialize the variable to some value so that it will have an appropriate length, as shown in the second example below.

Refer to Publish/Retrieve Encoding Behavior for information on how HTML files are published and how the optional encoding property can be used to provide encoding information to package recipients.

Examples

The following example retrieves HTML entry information from the package.

   data _null_;
   length contents $64  frame $64 pages $64 body $64
      contentsUrl $256  frameUrl $256 
         PagesUrl $256 bodyUrl $256;

      path ='/maintenance/schedule/doc';
   CALL RETRIEVE_HTML(entryId, path, body, 
      bodyUrl, frame, frameUrl, contents,
      contentsUrl, pages, pagesUrl, rc);

The following example uses a macro to initialize a variable to a specific length and then retrieves HTML information from the package.

   %macro initLen(variable, len);
      %let &variable=.;
      %do i=2 %to &len;
         %let &variable=&&&variable...;
      %end;
   %mend;

   %initLen(contents, 64);
   %initLen(contentsUrl, 256);
   %initLen(pages, 64);
   %initLen(pagesUrl, 256);
   %initLen(body, 64);
   %initLen(bodyUrl, 256);
   %initLen(frame, 64);
   %initLen(frameUrl, 256);
   %let path =/users/maintenance/doc;
   %let rc=0;
   %syscall RETRIEVE_HTML(entryId, path, body, 
      bodyUrl, frame, frameUrl, contents, contentsUrl, 
      pages, pagesUrl, rc);