COMPANION_NEXT

Retrieves the next companion HTML file in the ODS HTML set.

Syntax

CALL COMPANION_NEXT(entryId, path, filename, url, rc <, properties, propValue1, ...propValueN>);

entryId

Numeric, input.
Identifies the companion HTML file entry.

path

Character, input.
Specifies the full path of the location that will receive the retrieved file.

filename

Character, output.
Returns the name of the new file.

url

Character, output.
Returns the URL of the companion file.

properties

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

• ENCODING
• MIMETYPE

propValue1, ...propValueN

Character, 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. Valid property values are defined as follows:

ENCODING

Input character string specifies the target encoding for the companion file. The companion file is translated into the specified encoding. An example of a target encoding value is ISO-8859-1.

MIMETYPE

Character output parameter identifies the MIME type of the companion file. The MIME type is returned in the MIMETYPE variable. The publisher of the companion file can set the user-specified MIME type after the companion file is published. If the publisher does not specify the MIME type, the returned value is blank.

rc

Numeric, output.
Receives a return code.

Details

The publisher can choose to publish any combination of the HTML files. Included in the set of published files can be any number of additional HTML files or companion files.

The filename and url 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 file or the URL that is being returned. If not, the returned value will be truncated and a warning will be printed indicating that one or more parameters were truncated. When called from within the data step, use the LENGTH statement to define the length of the variable. When called from within a macro, initialize the variable to some value so that it will have an appropriate length.

For details about how HTML files are published and how the optional encoding property can be used to provide encoding information to package recipients, see Publish/Retrieve Encoding Behavior.

Examples

Example 1

The following example retrieves an HTML file and then retrieves the next companion HTML file in the set.

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

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

   CALL COMPANION_NEXT(entryId, path, fname, url, rc);

Example 2

The following example retrieves an HTML file and then retrieves the next companion HTML file in the set. If the publisher specifies a MIME type when publishing a package, the optional MIMETYPE property is specified in order for its MIME type to be returned. The MIME type will be returned in the mime variable.

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

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

   properties="MIMETYPE";
   CALL COMPANION_NEXT(entryId, path, fname, 
      url, rc, properties, mime);