Chapter Contents

Previous

Next
The TEMPLATE Procedure

DEFINE HEADER Statement


Creates a definition for a header.

Requirement: An END statement must be the last statement in the definition.
Featured in: Creating a New Table Definition


DEFINE HEADER header-path </ STORE=libname.template-store>;
<header-attribute-1; <... header-attribute-n; >>
DYNAMIC variable-1 <'text-1'> <... variable-n <'text-n'>>;
MVAR variable-1 <'text-1'> <... variable-n <'text-n'>>;
NMVAR variable-1 <'text-1'> <... variable-n <'text-n'>>;
NOTES 'text';
TEXT header-specification;
TEXT2 header-specification;
TEXT3 header-specification;
END;

To do this ... Use this statement
Set one or more header attributes. header-attribute(s)
Define a symbol that references a value that the data component supplies from the procedure or DATA step. DYNAMIC
Define a symbol that references a macro variable. ODS will use the value of the variable as a string. References to the macro variable are resolved when ODS binds the definition and the data component to produce an output object. MVAR
Define a symbol that references a macro variable. ODS will convert the variable's value to a number (stored as a double) before using it. References to the macro variable are resolved when ODS binds the definition and the data component to produce an output object. NMVAR
Provide information about the table. NOTES
Specify the text of the header. TEXT
Specify an alternative header to use in the Listing output if the header that is provided by the TEXT statement is too long. TEXT2
Specify an alternative header to use in the Listing output if the header that is provided by the TEXT2 statement is too long. TEXT3
End the header definition. END


Required Arguments

header-path
specifies where to store the header definition. A header-path consists of one or more names, separated by periods. Each name represents a directory in a template store. (A template store is a type of SAS file.) PROC TEMPLATE writes the definition to the first template store that you can write to in the current path.
Restriction: If the definition is nested inside another definition, definition-path must be a single-level name.
Restriction: If you want to reference the definition that you are creating from another definition, do not nest the definition inside another one. For example, if you want to reference a header definition from multiple columns, do not define the header inside a column definition.


Options

STORE=libname.template-store
specifies the template store in which to store the definition. If the template store does not exist, it is created.
Restriction: If the definition is nested inside another definition, you cannot use the STORE= option.
Availability: Version 8 of the SAS System


Header Attributes

This section lists all the attributes that you can use in a header definition. A column header spans a single column. A spanning header spans multiple columns. These two kinds of headers are defined in the same way except that a spanning header uses the START= or the END= attribute, or both.

For all attributes that support a value of ON, the following forms are equivalent:

ATTRIBUTE-NAME
ATTRIBUTE-NAME=ON
For all attributes that support a value of variable, variable can be any variable that you declare in the table definition with the DYNAMIC, MVAR, or NMVAR statement. If the attribute is a boolean, the value of variable should resolve to one of the following:

ON YES 0
_ON_ _YES_ FALSE
1 OFF NO
TRUE _OFF_ _NO_

To do this ... (table note 1) Use this attribute
Influence the appearance of the contents of the header

Specify whether or not to try to expand the column width to accommodate the longest word in the column header. FORCE=

Specify the horizontal justification for the column header. JUST=

Specify whether to try to divide the text equally among all lines or to maximize the amount of text in each line when the text in the header uses more than one line. MAXIMIZE=

Specify whether or not to draw a continuous line above the header. OVERLINE=

Specify whether or not to treat the text as preformatted text. PREFORMATTED=

Specify whether or not to print the header. PRINT=

Specify the number of blank lines to place between the current header and the next one or between the current footer and the previous one. SPACE=

Specify the split character for the header. SPLIT=

Specify the style element and any changes to its attributes to use for the header. STYLE=

Specify whether or not to start a new line of the header in the middle of a word. TRUNCATE=

Specify whether or not to draw a continuous line underneath the header. UNDERLINE=

Specify vertical justification for the header. VJUST=

Specify the width of the header in characters. WIDTH=
Influence the content of the header

Specify a character to use to expand the header to fill the space over the column or columns that the header spans. EXPAND=

Specify whether or not to repeat the text of the header until the space that is allotted for the header is filled. REPEAT=
Influence the placement of the header

Specify the last column that a spanning header covers. END=

Specify the first column that a spanning header covers. START=

Specify whether or not to expand the header to reach the sides of the page. EXPAND_PAGE=

Specify whether or not a spanning header appears only on the first data panel if the table is too wide to fit in the space that is provided. FIRST_PANEL=

Specify whether or not a table footer appears only on the last data panel if the table is too wide to fit in the space that is provided. LAST_PANEL

Specify whether or not to extend the text of the header into the header space of adjacent columns. SPILL_ADJ=

Specify whether or not to extend the text of the header into the adjacent margin. SPILL_MARGIN
Specify whether or not multiple columns can use the header. GENERIC=
Specify the header definition that the current definition inherits from. PARENT=

TABLE NOTE 1:  

Different attributes affect different ODS destinations. For details, consult the documentation for a specific attribute. [arrow]

END=column-name | variable
specifies the last column that a spanning header covers.
Default: the last column
See also: START=
ODS Destinations: All but Output

EXPAND='string' | variable
specifies a character to use to expand the header to fill the space over the column or columns that the header spans.
Default: none
Interaction: If you specify both REPEAT=ON and EXPAND=ON, PROC TEMPLATE honors EXPAND=.
See also: REPEAT=
Tip: If the string or the variable that you specify contains more than one character, PROC TEMPLATE uses only the first character.
See also: EXPAND_PAGE=
ODS Destinations: Listing

EXPAND_PAGE<= ON | OFF | variable>
specifies whether or not to expand the header to reach the sides of the page.
Default: OFF
See also: EXPAND=
ODS Destinations: Listing

FIRST_PANEL<= ON | OFF | variable>
specifies whether or not a spanning header appears only on the first data panel if the table is too wide to fit in the space that is provided.
Default: OFF
Restriction: Applies only to headers, not to footers
See also: LAST_PANEL=
ODS Destinations: Listing and Printer

FORCE<= ON | OFF | variable>
specifies whether or not to try to expand the column width to accommodate the longest word in the column header. The column width can be anything between the values for the WIDTH= and WIDTH_MAX= column attributes.
Default: ON
See also: WIDTH= and WIDTH_MAX=
ODS Destinations: Listing

GENERIC<= ON | OFF | variable>
specifies whether or not multiple columns can use the header.
Default: OFF
Restriction: This attribute is primarily for writers of SAS procedures and for DATA step programmers.
ODS Destinations: All but Output

JUST=justification | variable
specifies the horizontal justification for the column header, where justification can be one of the following:

Left
specifies left justification.
Alias: L

Right
specifies right justification.
Alias: R

Center
specifies center justification.
Alias: C

Default: The justification for the column
ODS Destinations: All but Output
Featured in: Customizing a Table Definition that a SAS Procedure Uses

LAST_PANEL<= ON | OFF | variable>
specifies whether or not a table footer appears only on the last data panel if the table is too wide to fit in the space that is provided.
Default: OFF
Restriction: Applies only to footers, not to headers
See also: FIRST_PANEL
ODS Destinations: Listing and Printer

MAXIMIZE<=ON | OFF | variable>
specifies whether to try to divide the text equally among all lines or to maximize the amount of text in each line when the text in the header uses more than one line. For example, if the text spans three lines, MAXIMIZE=ON might result in 45% of the text on the first line, 45% of the text on the second line, and 10% of the text on the third line. MAXIMIZE=OFF would may result in 33% of the text on each line. MAXIMIZE=ON may write lines of text that vary greatly in length. MAXIMIZE=OFF may result in using less than the full column width.
Default: OFF
ODS Destinations: Listing

OVERLINE<=ON | OFF | variable>
specifies whether or not to draw a continuous line above the header. PROC TEMPLATE uses the second formatting character to draw the line. (See the discussion of FORMCHAR=.)
Default: OFF
ODS Destinations: Listing

PARENT=header-path
specifies the header definition that the current definition inherits from. A header-path consists of one or more names, separated by periods. Each name represents a directory in a template store. (A template store is a type of SAS file.) The current definition inherits from the the specified header definition in the first template store that you can read from in the current path.

When you specify a parent, all the attributes and statements that are specified in the parent's definition are used in the current definition unless the current definition specifically overrides them.
ODS Destinations: All

PREFORMATTED<=ON | OFF | variable>
specifies whether or not to treat the text as preformatted text. When text is preformatted, ODS honors line breaks as well as leading, trailing, and internal spaces. It also renders the text in a monospace font.
Default: OFF
Interaction: When PREFORMATTED=ON, and you are defining a table header or a footer, ODS uses the headerfixed or the footerfixed style element unless you specify another style element with the STYLE= column attribute.

When PREFORMATTED=ON, and you are defining a column header, ODS uses the rowheaderfixed style element unless you specify another style element with the STYLE= column attribute.

ODS Destinations: HTML and Printer

PRINT<=ON | OFF | variable>
specifies whether or not to print the header.
Default: ON
Tip: When PRINT=ON, the column header becomes the label of the corresponding variable in any output data sets that the Output Destination creates if neither the column definition nor the data component provides a label.
ODS Destinations: All

REPEAT<=ON | OFF | variable>
specifies whether or not to repeat the text of the header until the space that is allotted for the header is filled.
Default: OFF
Interaction: If you specify both REPEAT=ON and EXPAND=ON, PROC TEMPLATE honors EXPAND=.
See also: EXPAND=
ODS Destinations: Listing

SPACE=positive-integer | variable
specifies the number of blank lines to place between the current header and the next one or between the current footer and the previous one.
Default: 0
Tip: A row of underlining or overlining is considered a header or a footer.
ODS Destinations: Listing
Featured in: Creating a New Table Definition

SPILL_ADJ<=ON | OFF | variable>
specifies whether or not to extend the text of the header into the header space of adjacent columns.
Default: OFF
Interaction: FORCE=, SPILL_MARGIN=, SPILL_ADJ=, and TRUNCATE= are mutually exclusive. If you specify more than one, PROC TEMPLATE honors only one. FORCE= takes precedence over the other three attributes, followed by SPILL_MARGIN= and SPILL_ADJ=.
See also: FORCE=, SPILL_MARGIN=, and TRUNCATE=
ODS Destinations: Listing

SPILL_MARGIN<=ON | OFF | variable>
specifies whether or not to extend the text of the header into the adjacent margin.
Default: OFF
Restriction: SPILL_MARGIN= applies only to a spanning header that spans all the columns in a data panel.
Interaction: FORCE=, SPILL_MARGIN=, SPILL_ADJ=, and TRUNCATE= are mutually exclusive. If you specify more than one, PROC TEMPLATE honors only one. FORCE= takes precedence over the other three attributes, followed by SPILL_MARGIN= and SPILL_ADJ=.
See also: FORCE=, SPILL_ADJ, and TRUNCATE=
ODS Destinations: Listing

SPLIT='character' | variable
specifies the split character for the header. PROC TEMPLATE starts a new line when it reaches that character and continues the header on the next line. The split character itself is not part of the header although each occurrence of the split character counts toward the maximum length for a label.
Tip: The first character in a header is automatically treated as a split character if it is not one of the following:

  • an alphanumeric character

  • a blank

  • an underscore (_)

  • a hyphen (-)

  • a period (.)

  • a percent sign (%).

ODS Destinations: All but Output

START=column-name | variable
specifies the first column that a spanning header covers.
Default: the first column
See also: END=
ODS Destinations: All but Output

STYLE=<style-element-name><[style-attribute-specification(s)]>
specifies the style element and any changes to its attributes to use for the header. Neither style-attribute-specification nor style-element-name is required. However, you must use at least one of them.

Note:   You can use braces ({ and }) instead of square brackets ([ and ]).   [cautionend]

style-element-name
is the name of the style element to use to render the header. The style element must be part of a style definition that is registered with the Output Delivery System. SAS Institute provides some style definitions. Users can create their own style definitions with PROC TEMPLATE (see DEFINE STYLE Statement). By default, ODS renders different parts of ODS output with different elements. For instance, by default, a table header is rendered with the style element header. The style elements that you would be most likely to use with the STYLE= attribute for a table header are

  • header

  • headerfixed

  • headerempty

  • headeremphasis

  • headeremphasisfixed

  • headerstrong

  • headerstrongfixed.

The style elements that you would be most likely to use with the STYLE= attribute for a table footer are

  • footer

  • footerfixed

  • footerempty

  • footeremphasis

  • footeremphasisfixed

  • footerstrong

  • footerstrongfixed.

The style elements that you would be most likely to use with the STYLE= attribute for a column header are

  • rowheader

  • rowheaderfixed

  • rowheaderempty

  • rowheaderemphasis

  • rowheaderemphasisfixed

  • rowheaderstrong

  • rowheaderstrongfixed.

The style element provides the basis for rendering the header. Additional style attributes that you provide can modify the rendering.

For information on finding an up-to-date list of the style definitions and for viewing a style definition so that you can see the style elements that are available, see Customizing Presentation Aspects of ODS Output. For information about the default style definition that ODS uses, see What Is the Default Style Definition Like?.

style-element-name can be either the name of a style element or a variable whose value is a style element.
Default: header

style-attribute-specification
describes the style attribute to change. Each style-attribute-specification has this general form:
style-attribute-name=style-attribute-value

For information on the style attributes that you can specify, see Style Attributes.

ODS destinations: HTML and Printer
Featured in: Customizing a Table Definition that a SAS Procedure Uses and Creating a New Table Definition

TRUNCATE<=ON | OFF | variable>
specifies whether or not to start a new line of the header in the middle of a word.

ON
Starts a new line of the header when the text fills the specified column width.

OFF
Extends the width of the column to accommodate the longest word in the column header, if possible.

Note:   TRUNCATE=OFF is the same as FORCE=ON.  [cautionend]

Default: OFF
Interaction: If you specify FORCE=, SPILL_MARGIN=, or SPILL_ADJ=, the TRUNCATE= attribute is ignored.
See also: FORCE=, SPILL_MARGIN=, and SPILL_ADJ=
ODS Destinations: Listing

UNDERLINE<=ON | OFF | variable>
specifies whether or not to draw a continuous line below the header. PROC TEMPLATE uses the second formatting character to draw the line. (See the discussion of FORMCHAR=.)
Default: OFF
ODS Destinations: Listing

VJUST=justification | variable
Specifies vertical justification for the header. justification can be one of the following:

TOP
places the header as high as possible.
Alias: T

CENTER
centers the header vertically.
Alias: C

BOTTOM
places the header as low as possible.
Alias: B

Default: BOTTOM
ODS Destinations: HTML and Printer

WIDTH=positive-integer | variable
specifies the width of the header in characters.
Default: If you do not specify a width, PROC TEMPLATE uses the column width.
Tip: If you want a vertical header, specify a width of 1.
ODS Destinations: Listing

DYNAMIC Statement


Defines a symbol that references a value that the data component supplies from the procedure or DATA step.

Scope: You can use the DYNAMIC statement in the definition of a table, column, header, or footer. A dynamic variable that is defined in a definition is available to that definition and to all the definitions that it contains.
Main discussion: DYNAMIC Statement


DYNAMIC variable-1 <'text-1'> <... variable-n <'text-n'>>;

MVAR Statement


Defines a symbol that references a macro variable. ODS will use the value of the variable as a string. References to the macro variable are resolved when ODS binds the definition and the data component to produce an output object.

Scope: You can use the MVAR statement in the definition of a table, column, header, or footer. A macro variable that is defined in a definition is available to that definition and to all the definitions that it contains.
Main discussion: MVAR Statement


MVAR variable-1 <'text-1'> <... variable-n <'text-n'>>;

NMVAR Statement


Defines a symbol that references a macro variable. ODS will convert the variable's value to a number (stored as a double) before using it. References to the macro variable are resolved when ODS binds the definition and the data component to produce an output object.

Scope: You can use the NMVAR statement in the definition of a table, column, header, or footer. A macro variable that is defined in a definition is available to that definition and to all the definitions that it contains.
Main discussion: NMVAR Statement


NMVAR variable-1 <'text-1'> <... variable-n <'text-n'>>;

NOTES Statement


Provides information about the header.

Tip: The NOTES statement becomes part of the compiled header definition, which you can view with the SOURCE statement, whereas SAS comments do not.


NOTES 'text';


Required Arguments

text
provides information about the header.

TEXT Statement


Specifies the text of the header or the label of a variable in an output data set.

Featured in: Creating a New Table Definition


TEXT header-specification(s);


Required Arguments

header-specification(s)
specifies the text of the header. Each header-specification can be one of the following:

_LABEL_
uses the label of the object that the header applies to as the text of the header. For instance, if the header is for a column, _LABEL_ specifies the label for the variable that is associated with the column. If the header is for a table, _LABEL_ specifies the label for the data set that is associated with the table.

text-specification(s)
specifies the text to use in the header. Each text-specification can be

  • a quoted string

  • a variable, followed by an optional format. The variable can be any variable that is declared in a DYNAMIC, MVAR, or NMVAR statement.

Note:   If the first character in a quoted string is neither a blank character nor an alphanumeric character, and SPLIT is not in effect, the TEXT statement treats that character as the split character. (See the discussion of SPLIT=.)  [cautionend]
Default: If you don't use a TEXT statement, the text of the header is the label of the object that the header applies to.
Tip: If the quoted string is a blank and it is the only item in the header specification, the header is a blank line.
Featured in: Creating a New Table Definition

TEXT2 Statement


Provides an alternative header to use in the Listing output if the header that is provided by the TEXT statement is too long.

See: TEXT Statement


TEXT3 Statement


Provides an alternative header to use in the Listing output if the header that is provided by the TEXT2 statement is too long.

See: TEXT Statement



Chapter Contents

Previous

Next

Top of Page

Copyright 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.