SAS 9.1 Output Delivery System Users Guide

PROC TEMPLATE ;

DEFINE TAGSET tagset- path </ STORE= libref . template-store >;

• < tagset-attribute-1 ; <... tagset-attribute-n ;>>

  • DEFINE EVENT event- name ;

  • < event-attribute-1 ; <... event-attribute-n >;>

  • statements ;

  • END ;

• NOTES ;

• END ;

DEFINE TAGSET Statement

Creates a tagset definition

Requirement: An END statement must be the last statement in the definition.

Featured in: All examples found in the 'Examples: Creating and Modifying Markup Languages Using the TEMPLATE Procedure' on page 588 section.

DEFINE TAGSET tagset-path </ STORE= libref . template-store < (READ WRITE

• UPDATE) >>;

• < tagset-attribute-1 ; <... tagset-attribute-n ;>>

• DEFINE EVENT event-name ;

statements and attributes

• NOTES 'text' ;

• END ;

Required Arguments

tagset-path

• specifies where to store the tagset definition.

• Requirement: A tagset-path consists of one or more names , separated by periods. Each name represents a directory, or level, in a template store.

• Default: PROC TEMPLATE writes the definition to the first template store in the current path where you have write access.

• Tip: You can control the item store where the tagset definition is stored by using the ODS PATH statement.

• Tip: Names are not case sensitive. However, PROC TEMPLATE uppercases the first letter for easy reading purposes.

Options

STORE= libref . template-store

• specifies the template store where the definition is stored in the following form:

  • libref . template-store < access-options >

• libref . template-store

  • specifies the current template store.

  • Default: If you omit an access-option , then the template-store is accessed with UPDATE permissions unless you have read-only access.

    Tip: If the specified template store does not exist, it is created.

• Interaction: Using the STORE= option overrides the search list specified in the PATH statement.

• Restriction: The STORE= option syntax does not become part of the compiled definition.

access-options

• specifies the access mode for the specified template store, where

• READ

  • provides read-only access.

• WRITE

  • provides write access as well as read access. If the tagset does not exist, then WRITE access creates a new tagset. If the tagset does exist, then WRITE access will not replace an existing tagset.

• UPDATE

  • provides update access as well as read access. If the tagset does not exist, then UPDATE will not create a new tagset. If the tagset does exist, then UPDATE will replace it.

Tagset Attributes

COPYRIGHT= '( text )'

• specifies the text to use as the copyright.

  Requirement: When specifying text , you must enclose the text in parentheses and then quotation marks.

DEFAULT_EVENT= ' event-name '

• specifies the name of an event to execute by default when the requested event cannot be found in the tagset definition.

  Requirement: When specifying an event-name , you must enclose the name of the event in quotation marks.

  Featured in: Example 3 on page 597

EMBEDDED_STYLESHEET= YES ON NO OFF

• specifies whether or not the tagset supports embedded stylesheets.

  Default: The default value is YES or ON which means that embedded stylesheets are supported.

  Tip: If embedded stylesheets are supported and no stylesheet is specified in the ODS statement, then the stylesheet is written to the top of the output file.

  YES

  • supports embedded stylesheets.

  • Alias: ON

• ON

  • supports embedded stylesheets.

    Alias: YES

• NO

  • does not support embedded stylesheets.

    Alias: OFF

• OFF

  • does not support embedded stylesheets.

    Alias: NO

INDENT= n

• indents output one or more indention levels, using the number of spaces specified by the INDENT= statement.

  Default: The default value for XML is 2. For all other ODS destinations, the default value is 0.

  ODS Destinations: MARKUP

  Featured in: Example 3 on page 597 and Example 5 on page 601

  n

  • specifies a numeric value for the number of spaces that you want the output to indent.

LOG_NOTE= ' string '

• defines a string that will be printed to the SAS log when the tagset is used.

  string

  • specifies the text that is printed to the SAS log.

    Requirement: You can not specify more than one string at a time.

MAP= ' characters '

• specifies the special characters that require translation.

  characters

  • specifies one or more special characters.

    Requirement: When listing special characters in the MAP= statement, do not use blank spaces between them.

    Requirement: When you specify special characters, you must enclose the list of special characters in quotation marks.

    Requirement: If you use the MAP= statement, you must also use the MAPSUB statement.

    Featured in: Example 3 on page 597

MAPSUB= ' strings '

• specifies the text to substitute for the characters that are specified in the MAP= statement.

  strings

  • Specifies the text strings to substitute for the characters that are specified in the MAP= statement.

    Requirement: When specifying multiple strings, you must use a forward slash (/) to separate the text strings.

    Requirement: When specifying strings, you must enclose the entire string list in quotation marks.

    Requirement: If you use the MAPSUB= statement, you must also use the MAP= statement.

• Featured in: Example 3 on page 597

NOBREAKSPACE= ' string '

• defines a nonbreaking space for the markup output.

  string

  • specifies the character that is used to define a nonbreaking space.

    Requirement: When specifying a string, you must enclose the string in quotation marks.

    Restriction: You can not specify more than one string at a time.

• Featured in: Example 3 on page 597

OUTPUT_TYPE= CSV HTML LATEX WML XML

• sets a category for the output.

  CSV

  • produces output with comma-separated values.

• HTML

  • produces hypertext markup language output.

• LATEX

  • produces output in LaTeX, which is a document preparation system for high-quality typesetting.

• WML

  • uses the Wireless Application Protocol (WAP) to produce a wireless markup language.

• XML

  • produces output in extensible markup language.

• Featured in: Example 3 on page 597

PARENT= tagset-path

• specifies the tagset definition from which the current definition inherits.

  tagset-path

  • specifies the name of a directory in a template store.

    Default: The current definition inherits from the specified definition in the first template store where you have read access permissions. The PATH statement specifies which locations to search for definitions that were created by PROC TEMPLATE, as well as the order in which to search for them.

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

    Requirement: When you specify a parent, all of the definition options, attributes, and statements that are specified in the parent's definition are used in the current definition unless the current definition overrides them.

    Tip: You can specify a tagset that SAS supplies or a tagset that you defined.

    Tip: You can control the item store from which the tagset definition is read by using the ODS PATH statement.

    Featured in: Example 1 on page 588 and Example 9 on page 610

REGISTERED_TM= '( text )'

• specifies the text to use as the registered trademark.

  Requirement: When specifying text , you must enclose the text in parentheses and then quotation marks.

SPLIT= ' string '

• defines a character string to use for line breaks in the markup output.

  Requirement: When specifying a string, you must enclose the string in quotation marks.

  Restriction: You cannot specify more than one string at a time.

  Featured in: Example 3 on page 597

STACKED_COLUMNS= YES ON NO OFF

• specifies whether or not the tagset allows procedures to place columns one on top of another, or side by side.

  Default: The default value is YES or ON, which means that columns are stacked .

  Tip: To place columns side by side, specify the NO or OFF value.

  Featured in: Example 3 on page 597 and Example 9 on page 610.

  YES

  • stacks columns one on top of another.

    Alias: ON

• ON

  • stacks columns one on top of another.

    Alias: YES

• NO

  • stacks columns side by side each other.

    Alias: OFF

• OFF

  • stacks columns side by side each other.

  • Alias: NO

TRADEMARK= '( text )'

• Specifies the text to use as the trademark.

  Requirement: When specifying text , you must enclose the text in parentheses and then quotation marks.

DEFINE EVENT Statement

Defines what is written to the output file

Interaction: Event statement conditions can be added to any DEFINE EVENT statement. For more information about event statement conditions, see 'Event Statement Conditions' on page 571

Featured in: Example 6 on page 603 and Example 7 on page 605

• DEFINE EVENT event-name ;

  • < event-attribute-1 ;<... event-attribute-n ;>>

  • BLOCK event-name </ event-condition-statements >;

  • BREAK </ event-condition-statements >;

  • CLOSE </ event-condition-statements >;

  • DELSTREAM stream-name </ event-statement-conditions >;

  • FLUSH < event-statement-conditions >;

  • NDENT </ event-statement-conditions >;

  • OPEN stream-name </ event-statement-conditions >;

  • PUT ' text '</ event-statement-conditions >;

  • PUTL </ event-statement-conditions >;

  • PUTLOG </ event-statement-conditions >;

  • PUTQ ' text ' event-variable </ event-statement-conditions >;

  • PUTSTREAM stream-name </ event-statement-conditions >;

  • PUTVARS variable- group </ event-statement-conditions >;

  • SET $ user-defined-event-variable user -defined-value </ event-statement-conditions >;

  • TRIGGER event-name < START FINISH ></ event-statement-conditions >;

  • UNBLOCK event-name </ event condition-statements >;

  • UNSET $ user-defined-event-variable ALL </ event-statement-conditions >;

  • XDENT </ event-statement-conditions >;

  • END </ event-statement-conditions >;

DEFINE Event Statement

Defines what is written to the output file

DEFINE EVENT event-name ;

• < event-attribute-1 ;<... event-attribute-n ;>>

Required Arguments

event-name

• specifies the name of the event.

Event Attributes

FILE= BODY CODE CONTENTS FRAME PAGES STYLESHEET

• redirects event output to any of the known types of output files that are open.

  Interaction: The names of the output files correspond to the output file names on the ODS MARKUP statement that are specified with the BODY=, CODE=, CONTENTS=, FRAME=, PAGES=, and STYLESHEET= parameters. For more information about the ODS MARKUP statement, see 'ODS MARKUP Statement' on page 109

  ODS Destinations: HTML, MARKUP

  See: For a complete description of the FILE= attribute, see the BODY= option in the ODS MARKUP statement.

PURE_STYLE= YES NO

• specifies whether to enable the event to use any style elements that have been defined.

  Default: NO

  ODS Destinations: MARKUP

  See also: 'DEFINE STYLE Statement' on page 288

  YES

  • enables the event to use any style elements that have been defined.

• NO

  • does not enable the event to use any style elements that have been defined.

STYLE= style-element ;

• specifies a style attribute that applies to a particular part of the output.

  ODS Destinations: HTML, MARKUP

  See also: 'DEFINE STYLE Statement' on page 288

  Tip: If you use a carriage return to separate your style attributes, then you must add a space before or after the carriage return to prevent syntax errors. SAS does not interpret a carriage return as a space.

  Featured in: Example 6 on page 603

BLOCK Statement

Disables the specified event

Tip: To enable the blocked event, use the UNBLOCK statement.

Tip: You can block the same event multiple times, but in order to enable the event, you must use the same number of UNBLOCK statements.

BLOCK event-name </ event-statement-conditions >;

Required Arguments

event-name

• specifies the name of the event.

Options

event-statement-conditions

• specifies event statement conditions that can be added to the BLOCK statement.

  See: For information about these options, see 'Event Statement Conditions' on page 571.

BREAK Statement

Stops an event from executing

Tip: The BREAK statement is most useful when combined with event conditions.

BREAK </ event-statement-conditions >;

Options

event-statement-conditions

• specifies event statement conditions that can be added to the BREAK statement.

  See: For information about these options, see 'Event Statement Conditions' on page 571.

CLOSE Statement

Closes the current stream and directs all future output to the output file

CLOSE </ event-statement-conditions >;

Options

event-statement-conditions

• specifies event statement conditions that can be added to the CLOSE statement.

  See: For information about these options, see 'Event Statement Conditions' on page 571.

DELSTREAM Statement

Deletes the specified stream

DELSTREAM stream-name </ event-statement-conditions >;

Required Arguments

stream-name

• specifies the name of the stream.

Options

event-statement-conditions

• specifies event statement conditions that can be added to the DELSTREAM statement.

  See: For information about these options, see 'Event Statement Conditions' on page 571.

FLUSH Statement

Writes any buffered output to the current output file or stream

FLUSH </ event-statement-conditions >;

Options

event-statement-conditions

• specifies event statement conditions that can be added to the FLUSH statement.

  See: For information about these options, see 'Event Statement Conditions' on page 571.

NDENT Statement

Indents output one more indention level than the number of spaces specified by the INDENT= statement

Interaction: The start position of the indention level is set by the INDENT= attribute.

Featured in: Example 3 on page 597 and Example 5 on page 601

NDENT </ event-statement-conditions >;

Options

event-statement-conditions

• specifies event statement conditions that can be added to the NDENT statement.

  See: For information about these options, see 'Event Statement Conditions' on page 571.

OPEN Statement

Opens the specified stream or creates one if the specified stream does not exist

Interaction: If another stream is open, then it will be closed when you specify a new stream to be opened.

Interaction: All text or variable data specified in the PUT statements that occur after the OPEN statement, will append to the stream instead of the output file.

OPEN stream-name </ event-statement-conditions >;

Required Arguments

stream-name

• specifies the name of the stream.

Options

event-statement-conditions

• specifies event statement conditions that can be added to the OPEN statement.

  See: For information about these options, see 'Event Statement Conditions' on page 571.

PUT Statement

Writes the text, or the value of an event variable to an output file

Requirement: You must enclose the text string in quotation marks.

Featured in: Example 1 on page 588, Example 3 on page 597, Example 4 on page 599, Example 5 on page 601, and Example 6 on page 603

PUT ' text ' VALUE < / event-statement-conditions >;

Required Argument

Options

event-statement-conditions

• specifies event statement conditions that can be added to the PUT statement.

  See: For information about these options, see 'Event Statement Conditions' on page 571.

PUTL Statement

Adds a new line to the end of the output

Alias: CR, NL, or LF

Tip: Use the PUTL statement when your event output is large.

PUTL </ event-statement-conditions >;

Options

event-statement-conditions

• specifies event statement conditions that can be added to the PUTL statement.

  See: For information about these options, see 'Event Statement Conditions' on page 571.

PUTLOG Statement

Writes the text, or the value of the event variable to the log

Requirement: You must enclose the text string in quotation marks.

PUTLOG ' text '</ event-statement-conditions >;

Required Argument

text

• specifies a text string that provides information about your output.

  Interaction: The PUTLOG statement pairs strings with variables. If a string is followed by a variable, they become a pair. If the variable has a value, then the pair becomes output. If the variable does not have value, then neither will be output.

  Requirement: The text must be enclosed in quotation marks.

Options

event-statement-conditions

• specifies event statement conditions that can be added to the PUTLOG statement.

  See: For information about these options, see 'Event Statement Conditions' on page 571.

PUTQ Statement

Places quotes around the value in an event variable or a style variable

Featured in: Example 7 on page 605

PUTQ ' text ' event-variable </ event-statement-conditions >;

Required Argument

text

• specifies a text string.

  Requirement: The text must be enclosed in quotation marks.

  Interaction: The PUTQ statement pairs strings with variables. If a string is followed by a variable, they become a pair. If the variable has a value, then the pair becomes output. If the variable does not have a value, then neither will be output.

event-variable

• specifies the event variable.

  See: 'List of Event Variables' on page 572.

Options

event-statement-conditions

• specifies event statement conditions that can be added to the PUTQ statement.

  See: For information about these options, see 'Event Statement Conditions' on page 571.

PUTSTREAM Statement

Writes the contents of the stream to the current output file

PUTSTREAM stream-name </ event-statement-conditions >;

Required Arguments

stream-name

• specifies the name of the stream.

Options

event-statement-conditions

• specifies event statement conditions that can be added to the PUTSTREAM statement.

  See: For information about these options, see 'Event Statement Conditions' on page 571.

PUTVARS Statement

Writes the name or value of an event, dynamic, memory, or stream variable to an output file

Interaction: The PUTVARS statement loops through all the variables in the variable group. Each iteration populates special variables which can be used in the format.

PUTVARS variable-group </ event-statement-conditions >;

Required Argument

variable-group

• specifies the variables to use in each iteration when you specify the name or value in the variable.

  Interaction: The PUTVAR statement pairs strings with variables. If a string is followed by a variable, they become a pair. If the variable has a value, then the pair becomes output. If the variable does not have a value, then neither will be output.

  EVENT

  • specifies the name of an event variable.

    See: 'List of Event Variables' on page 572

• STYLE

  • specifies the style elements available from the current ODS style definition being used.

• DYNAMIC

  • specifies the name of a dynamic variable.

• MEMORY

  • specifies the name of the variable created in the SET statement of the DEFINE EVENT statement.

    Requirement: Memory variables must be preceded by the '$' symbol.

• STREAM

  • specifies the name of the variable stream.

    Requirement: Stream variables must be preceded by the '$$' symbol.

Options

event-statement-conditions

• specifies event statement conditions that can be added to the PUTVARS statement.

  See: For information about these options, see 'Event Statement Conditions' on page 571.

SET Statement

Specifies a user-defined variable and its value

Requirement: The user-defined variable must be preceded by a '$' character.

Tip: User-defined variables are case insensitive.

SET $ user-defined-event-variable user-defined-value </ event-statement-conditions >;

Required Arguments

user-defined-event-variable

• specifies the name of the variable that you want to create.

  Requirement: The user-defined-event-variable must be preceded by a '$' character.

  Tip: User-defined-event-variables are case insensitive.

user-defined-value

• specifies the value of the user-defined-variable .

  Tip: Any value can be used for the user-defined-variable . You can assign an existing user-defined-variable name as a value for the variable.

Options

event-statement-conditions

• specifies event statement conditions that can be added to the SET statement.

  See: For information about these options, see 'Event Statement Conditions' on page 571.

TRIGGER Statement

Executes another event

Tip: The TRIGGER statement explicitly requests a specific action of an event.

Featured in: Example 3 on page 597, Example 4 on page 599, Example 5 on page 601, and Example 6 on page 603

TRIGGER event-name < START FINISH ></ event-statement-conditions >;

Required Arguments

event-name

• specifies the name of the event.

Without Options

If a triggered event does not have start or finish sections, then it will run the statements it does have.

Options

START

• specifies the start section of an event.

  Interaction: If you are in the start section of an event, then any event triggered will also run its start section.

FINISH

• specifies the finish section of an event.

  Interaction: If you are in the finish section of an event, then any event triggered will also run its finish section.

event-statement-conditions

• specifies event statement conditions that can be added to the TRIGGER statement.

  See: For information about these options, see 'Event Statement Conditions' on page 571.

UNBLOCK Statement

Enables a disabled event

Interaction: To disable an event, use the BLOCK statement.

Requirement: Because you can block the same event multiple times, in order to enable the event, you must use the same number of UNBLOCK statements as BLOCK statements.

UNBLOCK event-name </ event-statement-conditions >;

Required Arguments

event-name

• specifies the name of the event.

Options

event-statement-conditions

• specifies event statement conditions that can be added to the UNBLOCK statement.

  See: For information about these options, see 'Event Statement Conditions' on page 571.

UNSET Statement

Deletes the user-defined-variables and their values

Requirement: To specify the user-defined-variable , you must precede the name with a '$' character.

UNSET $ user-defined-event-variable ALL </ event-statement-conditions >;

Required Arguments

$user-defined-event-variable

• specifies the name of the variable that you want to delete.

• Requirement: The user-defined-event-variable must be preceded by a '$' character and no space.

  Tip: User-defined-event-variables are case insensitive.

ALL

• deletes all user-defined-event-variables .

Options

event-statement-conditions

• specifies event statement conditions that can be added to the UNSET statement.

• See: For information about these options, see 'Event Statement Conditions' on page 571.

XDENT Statement

Indents output one less indention level, using the number of spaces specified by the INDENT= attribute

Interaction: The starting level of indention is set by the INDENT= statement.

Featured in: Example 3 on page 597 and Example 5 on page 601

XDENT </ event-statement-conditions >;

Options

event-statement-conditions

• specifies event statement conditions that can be added to the XDENT statement.

• See: For information about these options, see 'Event Statement Conditions' on page 571.

END Statement

Ends the event definition

END ;

Event Statement Conditions

Conditions can be added to any DEFINE EVENT statement. A condition must be preceded with a slash (/).

event-statement </ event-statement-condition >;

Event Statement Conditions

event-statement

• specifies any of the DEFINE EVENT statements.

event-statement-condition

• specifies the type of condition.

  • Values for the event-condition-statements are one of the following:

• ANY

  • checks a list of variables for values. If any of the variables has a value, then the condition is true and the statement executes.

    • For example:

      put "One of our variables has a value!" nl/if any(background, foreground, cellpadding, cellspacing);

• CMP

  • compares , for equality, a string to a variable or list of variables.

    • For example:

      put "The foreground is blue!" nl/if cmp("blue",foreground);

• CONTAINS

  • searches the first argument for the second argument.

    For example:

    set $junk "some random text"; put "junk contains 'ran'" nl/if contains($junk, "ran");

• EXIST EXISTS

  • checks a variable, or a list of variables, to determine if a value exists. If all of the variables have a value, then the condition is true and the statement executes. If a variable has an empty string of length 0, then the value does not exist and the statement does not execute.

    For example:

    put "All of our variables have a value!" nl/if exists(background, foreground, cellpadding, cellspacing);

  • Tip: Use the MISSING event variable to determine if a value is missing.

• IF WHEN

  • tests for existence or equality. IF and WHEN are optional and interchangeable. An IF or WHEN condition compares values and strings or checks variables for values.

    For example, all of the following are equivalent:

    put "Foreground has a value!" nl/if exists(foreground); put "Foreground has a value!" nl/when exists(foreground); put "Foreground has a value!" nl/exists(foreground);

• NOT

  • negates a condition. You can use the keyword NOT or the characters '!' or '^'.

    For example:

    put "The foreground is not red!" nl/if !cmp("red", foreground);

Event Variables

List of Event Variables

Event variables include text, formatting, and data values. These variables originate from many places, such as the table definition, the procedure, title, byline processing, and more. Event variables also include any style attributes that you are using in your program. The following table lists the event variables that are used in the DEFINE EVENT statement of PROC TEMPLATE.

NOTES Statement

Provides information about the tagset definition

Tip: The NOTES statement becomes part of the compiled tagset definition, which you can view with the SOURCE statement.

Featured in: Example 3 on page 597 and Example 9 on page 610

NOTES ' text ';

Required Arguments

text

• provides information about the tagset.

END Statement

Ends the tagset definition

END ;