HTML Output Formatter

HTML Output Formatter Syntax Reference

The syntax for the HTML Output Formatter is

%OUT2HTM(argument=value, argument=value,...);

You must include the Output Formatter macro call with your SAS code. You cannot call it from a SAS command line. When including the macro call in your SAS code, you can use a list of arguments that are contained within parentheses and are separated with commas. You must end the call with a semicolon.

When naming files, you should avoid using certain reserved names. Click here to view a list of reserved names.

The Output Formatter macro uses the following types of arguments:

those that determine how the output is captured and saved
those that determine how the output is formatted
those that enable character transcoding
those that enable style sheets

Arguments that determine how the output is captured and saved

Most of the following arguments are required for the macro invocation. If the argument is required only in some cases, the exceptions are noted.

capture=ON | OFF

indicates the capture mode for the macro. When you want to format SAS output as HTML, you must first turn capturing on by including CAPTURE=ON as one of the arguments. Do not include any formatting arguments in the CAPTURE=ON statement. When turning capturing on for the Log, you must include WINDOW=LOG. (The Output Formatter looks at formatting arguments only when you turn capturing off, not on.)

To stop capturing and write the formatted HTML to the specified file, you must invoke the macro again and include CAPTURE=OFF in the parameter list. When turning capturing off for the Log window, you must include WINDOW=LOG. To specify formatting arguments and override the defaults set in the selected property list, enter formatting arguments in the CAPTURE=OFF clause.

Include a matching CAPTURE=OFF for each CAPTURE=ON argument for the window specified. For example, if you turn capturing on for the Log window, you must also turn it off for the Log window.

htmlfile=external-file

specifies the name of the HTML file where the formatted output will be written. If the file you specify does not exist, it is created for you. You must provide this argument when you turn capturing off.

Note: HTMLFILE and HTMLFREF are mutually exclusive arguments.

htmlfref=fileref

specifies the SAS fileref that points to the location of the HTML file where the formatted output will be written. If the file you specify does not exist, it is created for you. You must provide this argument when you turn capturing off.

Note: HTMLFILE and HTMLFREF are mutually exclusive arguments.

openmode=APPEND | REPLACE

indicates whether the new HTML output overwrites the information currently in the specified file or if the new output is appended to the end of the existing file. Specify APPEND to add your new HTML-enhanced output to the end of an existing file. This argument is required only if you want to override the default setting. Specify REPLACE to delete the information in an existing file and replace it with the new output. You must provide this argument when you turn capturing off.

Note: OPENMODE=APPEND is not valid is you are writing your resulting HTML to a PDS on z/OS.

proploc=property-list-name

specifies the name and location of your property list. This argument is required only if you are using a property list other than the default provided with the Output Formatter. The property list name must be a four-level name such as SASUSER.HTMLGEN.MYPROPS.SLIST.

putnfile=Y | N

enables you to add additional formatting information to your output using PUT and FILE statements. For more information, see PUT and FILE Support. Specify Y if you have modified your SAS program to use the enhanced formatting capabilities provided with PUT and FILE support. The default (N) indicates that this output does not contain special formatting instructions.

runmode=I | B

specifies whether you are running the macro in batch or interactive (window) mode. Although the default is to run the macro in batch mode, you should include RUNMODE=B when running in batch mode to avoid confusion. You must include the argument when running in interactive mode, which is available only with Release 6.12 of SAS software.

If you are using the Output Formatter with the Application Dispatcher, you must use RUNMODE=S. Using RUNMODE=S tells the formatter to print the HTTP header required by the Application Dispatcher before creating any output. For more information, refer to the SAS/IntrNet Application Dispatcher documentation at http://support.sas.com/documentation.

window=OUTPUT | LOG

specifies the SAS window from which you want to capture information. Note that all information in the specified window is formatted and saved to the specified file. You must include WINDOW=LOG, when turning capturing on or off for the Log window (the default is to capture information in the Output window).

Arguments that determine formatting characteristics

The remaining arguments provide formatting information and represent the properties that you can change to create customized HTML output.

To use the browser's attribute settings for those arguments below where DEFAULT is an option, specify DEFAULT. (Using DEFAULT tells the Output Formatter to ignore settings in the property list.) Otherwise, specify the value, for example, the color.

Note: The Output Formatter does not check for errors on fonts, colors, or sizes you specify. It simply allows any selection you type. So, you should specify values that are supported on the system where the HTML page will be viewed.

General page formatting

These arguments apply to the entire page for the current invocation of the macro. So, if you append data, the attributes of existing results will not change. You may want to use these arguments only when you replace, rather than append, pages. The rendering of some formatting arguments varies per browser. Some browsers may not support some of these options.

bgtype=NONE | COLOR | IMAGE

specifies the type of background for your Web page. If you specify COLOR or IMAGE as the value, you must also use the BG argument. Valid values for BGTYPE are

NONE: does not use a background on your Web page. This is the default.
COLOR: causes the Output Formatter to use the background color specified in the BG argument. If you specify COLOR as the value, you must also specify the color in the BG argument.
IMAGE: indicates that you want to use a custom image as a background. If you specify IMAGE as the value, you must also specify the BG argument to provide the name and location of the image. Some browsers may not support the use of background images.

bg=value

If you specified BGTYPE=IMAGE, this identifies the fully-qualified path and filename of a background image that you want to use on your Web page. If you specified BGTYPE=COLOR, this indicates the specific background color you want to use on your page. You can specify color values using the color name or the RGB value.

brtitle=value

specifies the value that appears as the title in the browser window title bar. By default, no title is displayed.

center=Y | N

determines whether all the output generated by the current invocation of the macro is centered. (See appending information under General Page Formatting.) The default is no center (N).

Note: Do not use CENTER when trying to line elements up in tabular output. The CENTER tag centers each line individually according to its line length and not according to the data and so may not line up as you want.

ctext=value | DEFAULT

indicates whether you use the default global text color defined by the browser or by the color specified here. This affects all the text generated by the current invocation of the macro. You can override the color for an element using the color specification arguments. For example, specifying a color for title lines in your property list or via the TCOLOR argument overrides the value specified by CTEXT. You can specify color values using the color name or the RGB value.

doctype=3.2 | value

specifies the information that is provided for the DOCTYPE tag in the HTML file. The default value is 3.2, which writes the following line to the top of your HTML file:

  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

If you want something other than the default text, you can provide the exact line to be added. If you supply a blank for value, nothing is added to the top of the file. If you supply a value other than 3.2, you must include the exact text that you want added. For example, if you want to reference a different DTD, you must provide the entire string, including !DOCTYPE and the opening and closing angle brackets.

encode=Y | N

specifies whether the Output Formatter replaces angle brackets with the appropriate ASCII character representation so that the brackets display in the browser. To have the Output Formatter check for the characters "<" and ">" and encode them as ASCII characters, specify Y. This displays the actual brackets in the browser. By default, the brackets are encoded. To have the Output Formatter pass the brackets to the browser (where the browser attempts to act on them as an HTML-formatting instruction), specify N.

pagepart=ALL | HEAD | BODY | FOOT

specifies which parts of the HTML page is written to the file. You may want to write only some parts of the page if you are appending the results to an existing file. The valid values are:

ALL: writes the HTML header information, your SAS output, and the HTML footer information to the specified file. This is the default behavior and it should be used when you are not appending additional information to the file.
HEAD: writes the HTML header information and your SAS output to the HTML file. It does not include the HTML footer information. You should use HEAD when you are going to append additional output from one of the Formatters to this file.
BODY: writes only your formatted SAS output to the specified file.
FOOT: writes your SAS output and the HTML footer information to the specified file.

For more information, see Using Page Formats.

saspower=value

adds the Powered by SAS logo to the bottom of the HTML page. You must provide the name and location of the image. This image automatically links to the SAS Web site. The value for this argument should be a fully-qualified pathname or valid URL. The default is not to display any image. Omit this argument if you do not want to use this image or have not acquired the logo.

Note: To display an image and automatically link to the SAS Web site when running in interactive mode, you must include the argument along with the %OUT2HTM macro call. The following example shows how to include the SASPOWER argument in interactive mode:

    %out2htm(runmode=i,
             saspower=saspower.gif);

Use of this image is by permission only. See the Powered by SAS logo guidelines and agreement.

septype=NONE | RULE | IMAGE

specifies the type of separator that you want to use between the pages of your output. The Output Formatter uses a separator whenever it encounters a page break in SAS output. Valid values are

NONE: overrides the default value and does not include a separator between the pages of your output.
RULE: the default. This value causes the Output Formatter to separate the pages of your output by adding <HR> (a horizontal rule) to the HTML file following the page end information supplied by the SAS procedure.
IMAGE: indicates that you want to use a custom image as a separator. If you specify IMAGE as the value, you must also specify the SEPLOC argument to provide the name and location of the image that you want to use.

seploc=image-location

specifies the name and location of the image that you want to use as a separator between pages of the output. This argument is required if you specify SEPTYPE=IMAGE. The value for this argument should be a fully-qualified pathname or valid URL.

Color specifications for output components

The next nine arguments provide color specifications for the output components title, footnote, byline, header, notes, warnings, errors, source, and data. When you specify any of these arguments, the HTML tag <FONT COLOR=value> is added to all the appropriate lines in your HTML-formatted output. You can specify color values by using the color name or the RGB values.

bcolor=value | DEFAULT: specifies the color for the bylines in your output.
dcolor=value | DEFAULT: specifies the color for the data lines in your output.
ecolor=value | DEFAULT: specifies the color for the error lines in your output.
fcolor=value | DEFAULT: specifies the color for the footnote lines in your output.
hcolor=value | DEFAULT: specifies the color for the header lines in your output.
ncolor=value | DEFAULT: specifies the color for the note lines in your output.
scolor=value | DEFAULT: specifies the color for the source lines in your output.
tcolor=value | DEFAULT: specifies the color for the title lines in your output.
wcolor=value | DEFAULT: specifies the color for the warning lines in your output.

Font specifications for output components

You can specify a custom font (or face) for each of the nine output components: title, footnote, byline, header, notes, warnings, errors, source, and data. When you specify any of these arguments, the HTML tag <FONT FACE=value> is added to all the appropriate lines in your HTML-formatted output. The default for each of these arguments is to use your browser font settings.

bface=value | DEFAULT
dface=value | DEFAULT
eface=value | DEFAULT
fface=value | DEFAULT
hface=value | DEFAULT
nface=value | DEFAULT
sface=value | DEFAULT
tface=value | DEFAULT
wface=value | DEFAULT

Size specifications for output components

You can also increase or decrease the default size of the text for each of the nine output components: title, footnote, byline, header, notes, warnings, errors, source, and data. When you specify any of these arguments, the HTML tag <FONT SIZE=value> is added to all the appropriate lines in your HTML-formatted output.

Valid values are N, +N, and -N, where N is an integer. Valid values are specific to each browser.

bsize=value | DEFAULT
dsize=value | DEFAULT
esize=value | DEFAULT
fsize=value | DEFAULT
hsize=value | DEFAULT
nsize=value | DEFAULT
ssize=value | DEFAULT
tsize=value | DEFAULT
wsize=value | DEFAULT

HTML tag specifications for output components

The remaining nine arguments allow you to change the HTML formatting tags that are associated with each component type. If you use these arguments to change the associated formatting tags, you may also change the font, size, and emphasis of the output component. This can cause undesired effects if you have also specified custom values for the arguments that control color, face, and size.

For a list of all of the valid HTML tag names that you can use with these arguments, see the list of available tags provided with the Output Formatter.

To display the results without specifying a tag for each of the following arguments, use NO FORMATTING for the value, for example, BTAG=NO FORMATTING. Otherwise, specify the tag name for VALUE.

btag=value: specifies the HTML tag name that is associated with bylines in your output. The default value is PREFORMATTED TEXT.
dtag=value: specifies the HTML tag name that is associated with data lines in your output. The default value is PREFORMATTED TEXT.
etag=value: specifies the HTML tag name that is associated with error lines in your output. The default value is PREFORMATTED + STRONG.

Note: The Output Formatter converts only those NOTE strings tagged with the SAS note attribute. If a "Note:" is not tagged this way, you may see the resulting text without the specified note lines formatting. The Output Formatter handles the line according to the settings for that particular line type.
ftag=value: specifies the HTML tag name that is associated with footnote lines in your output. The default value is PREFORMATTED + HEADER 3.
htag=value: specifies the HTML tag name that is associated with header lines in your output. The default value is PREFORMATTED + STRONG.
ntag=value: specifies the HTML tag name that is associated with note lines in your output. The default value is PREFORMATTED TEXT. Also, see the Note under the ETAG argument.
stag=value: specifies the HTML tag name that is associated with source lines in your output. The default value is PREFORMATTED TEXT.
ttag=value: specifies the HTML tag name that is associated with title lines in your output. The default value is PREFORMATTED + HEADER 3.
wtag=value: specifies the HTML tag name that is associated with warning lines in your output. The default value is PREFORMATTED + EMPHASIS. Also, see the note under the ETAG argument.

Arguments that enable character transcoding

tranlist=transcoding-list-name: specifies the name and location of an existing transcoding list. This argument is required only if you are implementing national language support. The transcoding list name must be a four-level name, and the fourth level must be SLIST.
charset=character-set-name: specifies the character set name that should appear in the <META> tag in your HTML file. HTML Formatting Tools do not perform any error checking on this value. Error handling of bad or unsupported character set names is provided by the user's browser.

Arguments that enable style sheets

Arguments that embed or link to your style sheets

The following arguments are valid for all formatters and are described in Syntax for Including Style Sheets:

Arguments that enable you to specify CLASS information

bclass=value: specifies the name of the style sheet class that should be applied to all bylines.
bdclass=value: specifies the name of the style sheet class to be used for the document body.
dclass=value: specifies the name of the style sheet class to be used for data lines.
eclass=value: specifies the name of the style sheet class to be used for error lines.
fclass=value: specifies the name of the style sheet class to be used for footnote lines.
hclass=value: specifies the name of the style sheet class to be used for header lines.
nclass=value: specifies the name of the style sheet class to be used for note lines.
sclass=value: specifies the name of the style sheet class to be used for source lines.
sepclass=value: specifies the name of the style sheet class to be used for the page separator. If the separator type is RULE, the supplied value is used on the CLASS attribute of the HR tag. If the separator type is IMAGE, the supplied value is used on the CLASS attribute of the IMG tag.
spclass=value: specifies the name of the style sheet class to be used for the Powered by SAS logo.
tclass=value: specifies the name of the style sheet class to be used for title lines.
wclass=value: specifies the name of the style sheet class to be used for warning lines.

Note: z/OS is the successor to the OS/390 and MVS operating systems. SAS/IntrNet 9.1 for z/OS is supported on the MVS, OS/390, and z/OS operating systems and, throughout this document, any reference to z/OS also applies to OS/390 and MVS, unless otherwise stated.