HTML Tabulate Formatter

HTML Tabulate Formatter Syntax Reference

The syntax for the HTML Tabulate Formatter is

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

You must include the Tabulate 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 invocation with a semicolon.

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

Note: Table support varies across browsers. Some of the formatting attributes supported by the Tabulate Formatter are not recognized by all browsers. In most cases, a browser will ignore HTML tags that it does not recognize; however, this may produce undesirable output.

The Tabulate Formatter macro lets you change how information is saved and formatted, described in the following sections of this page:

Arguments that determine how PROC TABULATE output is captured and saved
Arguments that determine formatting characteristics
Arguments that enable character transcoding.
Arguments that enable style sheets

Arguments that determine how PROC TABULATE 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 PROC TABULATE 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. (The Tabulate 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. To specify formatting arguments and override the defaults set in the selected property list, enter formatting arguments when you stop capturing. Remember to include a matching CAPTURE=OFF for each CAPTURE=ON argument.

IMPORTANT: Be sure that your program generates output only from PROC TABULATE while capturing is turned on. The HTML Tabulate Formatter will fail or produce unpredictable results if other type of output is also captured. To capture other types of output, use the HTML Output Formatter.

formchar=value

specifies the form characters that are used to create the outline for the PROC TABULATE output. The value must be 11 unique characters, specified using their hexadecimal values. This option is required only if you are defining an alternate set of form characters. For more information about FORMCHAR requirements, see Setting SAS System Options.

htmlfile=external-filename

specifies the name of the HTML file where the formatted output is written. If the file you specify does not exist, it is created for you.

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 should be written. If the file you point to does not exist, it is created for you.

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 the it 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. REPLACE, the default, deletes the information in an existing file and replaces it with the new output.

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. The property list name must be a four-level name, such as SASUSER.HTMLGEN.MYPROPS.SLIST.

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 Tabulate 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.

Arguments that determine formatting characteristics

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

Note: The Tabulate Formatter does not check for errors on fonts, colors, or sizes you specify. It simply allows any value 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 do not change. You may want to use these arguments only when you replace, rather than append, pages. The rendering of some formatting arguments vary per browser. Some browsers may not support all of these options.

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

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 Tabulate 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 text that appears in the browser window title bar. By default, no specific title is displayed.

center=Y | N

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

ctext=value | DEFAULT

indicates the global text color. The color can be defined by the browser or by the value 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 Tabulate Formatter replaces angle brackets with the appropriate ASCII character representation so that the brackets display in the browser. To have the Tabulate Formatter check for the characters "<" and ">" and encode them as ASCII characters, select Y. This will display the actual brackets in the browser. By default, the brackets will be encoded. To not encode them and have the Tabulate Formatter pass the brackets to the browser (where the browser will attempt 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 %TAB2HTM macro call. The following example shows how to include the SASPOWER argument in interactive mode:

    %tab2htm(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 in your output. The Tabulate Formatter uses a separator whenever it encounters a page break in PROC TABULATE output. Valid values are the following:

NONE: overrides the default value and does not include a separator between the pages in your output.
RULE: This is the default. This value causes the Tabulate Formatter to separate the pages in your output by adding the <HR> tag (a horizontal rule) to the HTML file following the end of the page.
IMAGE: indicates that you want to use a custom image as a separator. If you specify IMAGE, 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 location of the image that you want to use as a separator between pages in 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.

General table definition

Use the following attributes to define the formatting structure of the table. These attributes contribute information to the HTML <TABLE> tag.

border=Y | N: turns borders on or off for the table. The default value is Y, which turns borders on for the table. The width of the border is determined by the value of the BWIDTH argument.
bwidth=value: specifies the thickness of the border. The higher the number, the thicker the border. The default value is 1.
cpad=value: specifies the space, in pixels, between the borders of the table cell and the contents within the cell. The default value is 1. The value specified for this argument is represented in the HTML as CELLPADDING.
cspace=value: specifies the space, in pixels, between the cells in the table. The default value is 1. The value specified for this argument is represented in the HTML as CELLSPACING.
talign=LEFT | CENTER | RIGHT: indicates whether the table is aligned to the left, right, or center of the page. The default value is CENTER. Some browsers produce unexpected results with multiple tables and anything other than CENTER.
tbbgcolr=value | DEFAULT: specifies a background color for the entire table. Individual cell background colors can be specified using the BXBGCOLR, CLBGCOLR, RLBGCOLR, or DBGCOLR arguments, which override the setting of TBBGCOLR.
twidth=value: specifies the width of the table. The default value is 0, which lets the browser determine the optimum table width. The units for this value are determined by the TWUNITS argument.
twunits=PERCENT | PIXELS: specifies the units used to determine the table width. The default value is PERCENT.

Table element formatting introduction

The remainder of the arguments control the formatting of individual elements in the PROC TABULATE output. The illustration shows all of the table elements that can be customized using HTML Tabulate Formatter along with their arguments.

The following three elements require some explanation:

The Table Caption displays text that PROC TABULATE uses as the page dimension, unless BOX=PAGE is specified. If so, then the text used as page dimension will be displayed in the box cell.
The Box cell, the cell in the upper left corner of the table, displays any value set by the BOX option of PROC TABULATE.
The continuation line is the line containing the string (CONTINUED) that PROC TABULATE generates when a table is split across a page.

For further details, refer to the SAS Procedures Guide.

Here's another way to look at how the Tabulate Formatter lets you change format options. The following illustration lists the table elements and indicates whether you can change the text color, font, font size, background color, or vertical or horizontal alignment. To go directly to the section that describes a table element, click on that element name in the following table:

**Formatting Options for Table Elements**
Table element	Text color	Font and font size	Background color	Alignment	HTML tag
Title lines	Yes	Yes			Yes
By lines	Yes	Yes			Yes
Table caption	Yes	Yes		Yes	Yes
Table box cell	Yes	Yes	Yes	Yes	Yes
Table column label cells	Yes	Yes	Yes	Yes	Yes
Table row label cells	Yes	Yes	Yes	Yes	Yes
Table data cells	Yes	Yes	Yes	Yes	Yes
Continuation line	Yes	Yes			Yes
Footnote lines	Yes	Yes			Yes

Individual table element formatting

The following information describes each of the arguments that control the formatting of individual elements in the PROC TABULATE output. If you specify formatting information for an element not included in your table, the information is ignored.

To use the browser's attribute settings for those arguments below where DEFAULT is an option, specify DEFAULT. (Using DEFAULT tells the Tabulate Formatter to ignore settings in the property list.) Otherwise, specify the value, for example, the color. This applies only to color, face, and size arguments; it does not apply to tag or alignment arguments.

When you specify any of these arguments, an HTML tag such as <FONT COLOR=value> is added to all the appropriate lines in your HTML-formatted output.

The title lines

tcolor=value | DEFAULT: specifies a color for the SAS title lines. You can specify color values using the color name or the RGB value.
tface=value | DEFAULT: specifies a font for the SAS title lines. Valid values are browser specific.
tsize=value | DEFAULT: specifies the size of the font used to display SAS title lines. Valid values are N, +N, and -N, where N is an integer. Valid values for N are browser specific.
ttag=value: specifies the HTML tag name associated with the SAS title lines. The default value is PREFORMATTED + HEADER 3.
For a list of all of the valid HTML tag names that you can use with this argument, see the list of available tags provided with the Tabulate Formatter.

The by lines

bcolor=value | DEFAULT: specifies a color for the SAS by lines. You can specify color values using the color name or the RGB value.
bface=value | DEFAULT: specifies a font for the SAS by lines. Valid values are browser specific.
bsize=value | DEFAULT: specifies the size of the font used to display SAS by lines. Valid values are N, +N, and -N, where N is an integer. Valid values for N are browser specific.
btag=value: specifies the HTML tag name associated with the SAS by lines. The default value is PREFORMATTED TEXT.
For a list of all of the valid HTML tag names that you can use with this argument, see the list of available tags provided with the Tabulate Formatter.

The table caption

The table caption displays text that PROC TABULATE uses as the page dimension. Refer to the subsection entitled Table element formatting introduction for more information.

ccolor=value | DEFAULT: specifies the color of the caption text. You can specify color values using the color name or the RGB value.
cface=value | DEFAULT: specifies a font for the caption text. Valid values are browser specific.
chalign=LEFT | CENTER | RIGHT: specifies the location of the caption text. The default value, LEFT, aligns the caption text to the left. Specify RIGHT (or CENTER) if you want the caption text aligned to the right (or center).
csize=value | DEFAULT: specifies the size of the font used to display the caption text. Valid values are N, +N, and -N, where N is an integer. Valid values for N are browser specific.
ctag=value: specifies the HTML tag name associated with the caption. The default value is NO FORMATTING.
For a list of all of the valid HTML tag names that you can use with this argument, see the list of available tags provided with the Tabulate Formatter.
cvalign=TOP | BOTTOM: specifies the location of the caption text. The default value, TOP, locates the caption text above the table. Specify BOTTOM if you want the caption text to appear below the table.

The table box cell

The box cell is the cell that is generated by the BOX option of PROC TABULATE. Refer to the subsection entitled Table element formatting introduction for more information.

bxbgcolr=value | DEFAULT: specifies a background color for the box cell. You can specify color values using the color name or the RGB value.
bxcolor=value | DEFAULT: specifies the color of the box cell text. You can specify color values using the color name or the RGB value.
bxface=value | DEFAULT: specifies a font for the box cell text. Valid values are browser specific.
bxhalign=LEFT | RIGHT | CENTER: specifies the horizontal location of the box cell text within the table cell. The default is to place the text at the left of the cell.
bxsize=value | DEFAULT: specifies the size of the font used to display the box cell text. Valid values are N, +N, and -N, where N is an integer. Valid values for N are browser specific.
bxtag=value: specifies the HTML tag name associated with the box cell text. The default value is NO FORMATTING.
For a list of all of the valid HTML tag names that you can use with this argument, see the list of available tags provided with the Tabulate Formatter.
bxvalign=TOP | BOTTOM | MIDDLE | BASELINE: specifies the vertical location of the box cell text within the table cell. The default is to place the text at the top of the cell.
bxwrap=Y | N: turns wrapping on or off for box cell text. The default for this argument is no wrapping (N), which is consistent with the behavior in previous releases.

The table column labels

clbgcolr=value | DEFAULT: specifies a background color for the column label cells. You can specify color values using the color name or the RGB value.
clcolor=value | DEFAULT: specifies the color of the column label text. You can specify color values using the color name or the RGB value.
clface=value | DEFAULT: specifies a font for the column label text. Valid values are browser specific.
clhalign=LEFT | RIGHT | CENTER: specifies the horizontal location of the column label text within the table cell. The default is to center the text within the cell.
clsize=value | DEFAULT: specifies the size of the font used to display the column label text. Valid values are N, +N, and -N, where N is an integer. Valid values for N are browser specific.
cltag=value: specifies the HTML tag name associated with the column label text. The default value is NO FORMATTING.
For a list of all of the valid HTML tag names that you can use with this argument, see the list of available tags provided with the Tabulate Formatter.
clvalign=TOP | BOTTOM | MIDDLE | BASELINE: specifies the vertical location of the column label text within the table cell. The default is to place the text at the bottom of the cell.
clwrap=Y | N: turns wrapping on or off for column label text. The default for this argument is no wrapping (N), which is consistent with the behavior in previous releases.

The table row labels

rlbgcolr=value | DEFAULT: specifies a background color for the row label cells. You can specify color values using the color name or the RGB value.
rlcolor=value | DEFAULT: specifies the color of the row label text. You can specify color values using the color name or the RGB value.
rlface=value | DEFAULT: specifies a font for the row label text. Valid values are browser specific.
rlhalign=LEFT | RIGHT | CENTER: specifies the horizontal location of the row label text within the table cell. The default is to place the text at the left of the cell.
rlsize=value | DEFAULT: specifies the size of the font used to display the row label text. Valid values are N, +N, and -N, where N is an integer. Valid values for N are browser specific.
rltag=value: specifies the HTML tag name associated with the row label text. The default value is NO FORMATTING.
For a list of all of the valid HTML tag names that you can use with this argument, see the list of available tags provided with the Tabulate Formatter.
rlvalign=TOP | BOTTOM | MIDDLE | BASELINE: specifies the vertical location of the row label text within the table cell. The default is to place the text at the top of the cell.
rlwrap=Y | N: turns wrapping on or off for the row label text. The default for this argument is no wrapping (N), which is consistent with the behavior in previous releases.

The table data cells

dbgcolr=value | DEFAULT: specifies a background color for the data cells. You can specify color values using the color name or the RGB value.
dcolor=value | DEFAULT: specifies the color of the data cell text. You can specify color values using the color name or the RGB value.
dface=value | DEFAULT: specifies a font for the text used for each data cell in the table. Valid values are browser specific.
dhalign=LEFT | RIGHT | CENTER: specifies the horizontal location of the data cell text within the table cell. The default is to place the text at the right the cell.
dsize=value | DEFAULT: specifies the size of the font used to display the data cell text. Valid values are N, +N, and -N, where N is an integer. Valid values for N are browser specific.
dtag=value: specifies the HTML tag name associated with the data cell text. The default value is NO FORMATTING.
For a list of all of the valid HTML tag names that you can use with this argument, see the list of available tags provided with the Tabulate Formatter.
dvalign=TOP | BOTTOM | MIDDLE | BASELINE: specifies the vertical location of the data cell text within the table cell. The default is to place the text at the bottom of the cell.
dwrap=Y | N: turns wrapping on or off for the text in a data cell. The default for this argument is no wrapping (N), which is consistent with the behavior in previous releases.

The continuation line

PROC TABULATE generates the continuation line, which contains the string (CONTINUED) when a table splits across pages. Refer to the subsection entitled Table element formatting introduction for more information.

cncolor=value | DEFAULT: specifies a color for the continuation line. You can specify color values using the color name or the RGB value.
cnface=value | DEFAULT: specifies a font for the continuation line. Valid values are browser specific.
cnsize=value | DEFAULT: specifies the size of the font used to display the continuation line. Valid values are N, +N, and -N, where N is an integer. Valid values for N are browser specific.
cntag=value: specifies the HTML tag name associated with the continuation line. The default value is BOLD + ITALICIZED.
For a list of all of the valid HTML tag names that you can use with this argument, see the list of available tags provided with the HTML Tabulate Formatter.

The footnote lines

fcolor=value | DEFAULT: specifies a color for the SAS footnote lines. You can specify color values using the color name or the RGB value.
fface=value | DEFAULT: specifies a font for the SAS footnote lines. Valid values are browser specific.
fsize=value | DEFAULT: specifies the size of the font used to display the SAS footnote lines. Valid values are N, +N, and -N, where N is an integer. Valid values for N are browser specific.
ftag=value: specifies the HTML tag name associated with the SAS footnote lines. The default value is PREFORMATTED + HEADER 3.
For a list of all of the valid HTML tag names that you can use with this argument, see the list of available tags provided with the HTML Tabulate Formatter.

Arguments that enable character transcoding

Note: Character transcoding is available only in version 1.1 and higher.

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 the CLASS and ID information

bclass=value: specifies the name of the style sheet class that should be applied to all byline labels.
bdclass=value: specifies the name of the style sheet class to be used for document body.
bxclass=value: specifies the name of the style sheet class that should be applied to the box cell.
cclass=value: specifies the name of the style sheet class to be used for the table caption.
clclass=value: specifies the name of the style sheet class to be used for the column label cells.
cnclass=value: specifies the name of the style sheet class to be used for continuation lines.
dclass=value: specifies the name of the style sheet class to be used for the data cells.
fclass=value: specifies the name of the style sheet class to be used for footnote lines.
rlclass=value: specifies the name of the style sheet class to be used for the row label cells.
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. For an IMAGE separator, 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.
tbclass=value: specifies the name of the style sheet class to be used for the table.

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.