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> );

Required Arguments

entryId
identifies the companion HTML file entry.
Type:Numeric, Input
path
specifies the full path of the location that will receive the retrieved file.
Type:Character, Input
filename
returns the name of the new file.
Type:Character, Output
url
returns the URL of the companion file.
Type:Character, Output
rc
receives a return code.
Type:Numeric, Output

Optional Arguments

properties
identifies a comma-separated list of optional property names. Valid property names are as follows:
  • ENCODING
  • MIMETYPE
Type:Character, Input
propValue1, …propValueN
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 that 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 that 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, then the returned value is blank.
Type:Character, Input

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 and Retrieve Encoding Behavior .

Examples

Example 1: Using COMPANION_NEXT

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: Using COMPANION_NEXT with Specified MIME Type

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, then 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);