Concepts: Markup Languages and the TEMPLATE Procedure | SAS 9.1 Output Delivery System Users Guide

Getting Familiar with Tagsets

Listing Tagset Names

SAS provides a set of tagset definitions. To get a list of the tagset names that SAS supplies , plus any tagsets that you created and stored in the SASHELP.TMPLMST template store, submit the following SAS statements:

 proc template;     list tagsets;  run;

By default, PROC TEMPLATE lists the tagsets in SASHELP.TMPLMST and SASUSER.TEMPLAT. Typically, you have read-only access permissions to the SASHELP.TMPLMST item store where the SAS tagset directory is located. The SASUSER.TEMPLAT is the item store where the tagsets that you create or customize are stored by default.

Note: The tagset names that begin with SAS are used by the XML LIBNAME engine and are supported by SAS. For example, TAGSETS.SASXMOG and TAGSETS.SASXMOIM are fully supported by SAS.

Specifying Tagset Names

To specify a SAS tagset stored in SASHELP.TMPLMST or a tagset that you created and stored in SASUSER.TEMPLAT or any other item store, use a two-level name : TAGSETS. tagset-name . For example, tagsets. chtml or tagsets.mytagset are valid two-level tagset names. By default, SAS knows that the specified tagset is stored in either SASHELP.TMPLMST or SASUSER.TEMPLAT.

To specify a tagset that you created and stored in an item store other than SASUSER.TEMPLAT, assign the item store to the ODS search path with the ODS PATH statement. For information about the ODS PATH statement, see 'ODS PATH Statement' on page 149

Viewing the Contents of a Tagset Definition

To view the contents of a tagset definition, you can use the SAS windowing environment or the TEMPLATE procedure.

SAS Windowing Environment
1. From the menu, select
  
  View – Results
2. In the Results window, select the Results folder. Right-click and select Templates to open the Templates window.
3. Double-click on Tagsets to view the contents of that item store or directory.
4. Double-click on the tagset definition that you wish to view. For example, the CHTML tagset definition is the template store for CHTML output.

SAS Windowing Command
1. To view the Templates window, submit the following command in the command bar:
```
 odstemplates 
```
  The Templates window contains the item stores Sasuser.Templat and Sashelp.Tmplmst .
2. When you double-click an item store, such as Sashelp.Tmplmst , that item store expands to list the directories where ODS templates are stored. The templates that SAS provides are in the item store Sashelp.Tmplmst.
3. To view the tagset definitions that SAS provides, double-click the Tagset item store.
4. Right-click the tagset definition, such as Rtf , and select Open. The tagset definition is displayed in the Template Browser window.

TEMPLATE Procedure
1. To see the source for a tagset definition, use PROC TEMPLATE and specify the two-level name of the tagset. For example, to see the source of a SAS tagset that generates CHTML output, submit these SAS statements:
```
 proc template;        source tagsets.chtml; 
```
  If you look at the source for TAGSETS.CHTML, you see that it consists of:
  - a DEFINE TAGSET statement that names the tagset definition
  - event definitions that define what is written to the output file
  - tagset definition attributes, such as output type and the character to use for line breaks.

What Are Events?

A tagset definition controls output generation through a series of events and variables . An event defines what is written to the output file. Here are some key points about events:

Events have unique names. SAS procedures that generate ODS output use a standard set of events, which you can customize by redefining them in your own tagset definition. In addition, you can define your own events.
The DEFINE EVENT statement assigns a name to an event definition
An event definition can include start and/or finish sections that specify different actions. If the event definition does not include either a start or finish section, the event is stateless, which means that no matter how the event is called, all of the actions in the event are executed. If an event has a finish section, a start section is assumed if there are statements above the finish section.
An event definition can execute another event using the TRIGGER statement. If you are in the start section of an event, then any event triggered will also run its start section. If you are in the finish section, then the triggered event will run its finish section. If a triggered event does not have start or finish sections, then it will run the statements that it does have. A trigger can also explicitly ask for an event's specific section. See Example 4 on page 599
Events can perform actions based on conditions.
For the most part, an event consists of PUT statements, text, and event variables

For example, here is a simple event definition for an HTML table output.

 define event table;[1]  start:[2]        put "<table>" nl;  finish:        put "</table>" nl;  end;

In the event definition:

[1]

The DEFINE EVENT statement begins the event and assigns it the name TABLE.

[2]

The START section defines the beginning portion for the event, and the FINISH section defines the ending portion of the event. An event definition for a table needs START and FINISH sections because ODS needs to know how to define the beginning and how to define the ending. ODS will also expect other events to define how to format the table's rows and columns . The PUT statements specify to write the tags <table> and </table> to the output file, along with a new line after each tag.

The following event definition does not include a start and finish section, and the PUT statements specify to write the tags <TD> and </TD> to the output file. In addition, the event variable VALUE is used so that the data value, from the SAS procedure or data set, is written to the output file, enclosed with the <TD> and </TD> tags.

 define event data;        put "<TD>";        put VALUE;        put "</TD>";  end;

What Are Variables?

A variable is a programming structure used to hold data. A variable holds the data assigned to it until a new value is assigned or the program is finished. Each variable has a unique name and holds information that either is internal information to handle the requested output (metadata used by ODS or the XML LIBNAME engine) or is directly related to the output itself. For example, the variable COLCOUNT holds the value for the number of columns in the output, and the variable DATE holds the date.

Variables used by tagsets can be divided into two groups: internally generated and user created.

There are 3 logical divisions of internally generated variables:

event variables	include text, formatting, and data values. These variables can originate in many places such as the table definition, the procedure, title, or byline processing.
style variables	are specified by the ODS style attributes currently in use. The style variables are only differentiated from other event variables in that you know exactly where they originate.
dynamic variables	are dynamically created within SAS. Because they are dynamically created, their names, or how they are used, is unknown. These variables are dynamic because they are not defined by ODS but rather the variables are defined by applications such as SAS/GRAPH and the XML LIBNAME engine. Dynamic variables are designated by a preceding @ symbol. Dynamic variables can be listed with the 'DYNAMIC Statement' on page 425. For more information about SAS/GRAPH, see SAS/GRAPH Reference, Volumes 1 and 2 .

There are two types of user-created variables:

memory variables	are created with the SET statement, within the DEFINE EVENT statement. Once created, memory variables are globally available in all events. They persist until they are deleted. Memory variables are designated by a preceding '$' symbol.
stream variables	are different from memory variables in that they can hold very large amounts of data. They can hold very large amounts of data because as they grow, they are written to disk as needed. Opening a stream variable redirects all output from the put statements to the stream, until it is closed. Stream variables can also be opened, closed, flushed, set and unset.

Displaying Event Variables and Their Values

Because variables represent data, their values may or may not be present, depending on the SAS procedure and the job. For example, some variables have values only if you specified them with procedure options or style options. Other variables have values because the internal information is needed, such as how many columns are in the output. For example, TAGSETS.CHTML contains the event definition COLSPECS, which uses the event variable COLCOUNT so that ODS knows how many columns are in the output:

 define event colspecs;        put "<p>" nl "<table";        putq " columns=" COLCOUNT;        put " cellpadding=2 border=1>" nl;  end;

To determine which variables have values and what the values are, submit your SAS program using the EVENT_MAP statement. For more information, see ' Defining a Tagset Using the EVENT_MAP Tagset' on page 586. For a list of event variables and their descriptions, see 'List of Event Variables' on page 572.

Creating Your Own Tagsets

Methods for Creating Your Own Tagsets

To create a tagset, you use the TEMPLATE procedure to define the tagset definition. In general, there are three methods that you can use to create your own tagset.

Define a tagset definition through inheritance.
Copy an existing tagset definition, then modify it.
Define your own tagset definition.

Inheriting Events in a Tagset Definition

Tagsets can inherit events from each other. For example, the SAS tagset TAGSETS.WMLOLIST inherits most of its events from TAGSETS.WML, and TAGSETS.IMODE gets most of its events from TAGSETS.CHTML. Inheriting events from an existing tagset definition is the easiest way to define a new tagset definition.

To inherit events, a tagset definition uses the PARENT= attribute in the DEFINE TAGSET statement to specify the name of a tagset from which to inherit. When a parent is specified for a tagset definition, all of the tagset options, attributes, and statements that are specified in the parent's definition are used in the new definition unless the new definition overrides them. That is, in the new tagset definition, an event can override the operation of the same-named event defined in the parent tagset. For example, if the parent tagset defines an event named TABLE, you can change the operation in the new tagset by redefining the event named TABLE.

For an example of inheriting events in a tagset definition, see Example 1 on page 588

Defining a Tagset Using the EVENT_MAP Tagset

SAS procedures that generate ODS output use a standard set of events and variables. To generate customized output, you can create your own tagset with customized events. However, in order to customize the events, you must know the names of the events that ODS uses.

A good way to start defining your customized tagset is to use the EVENT_MAP tagset that SAS supplies in order to determine which events are triggered and which variables are used by an event to send output from a SAS process to an output file. When you run a SAS process with TAGSETS.EVENT_MAP, ODS writes XML markup to an output file that shows all event names and variable names as tags. In the output, tag names are the event names. Tag attributes are the variables that have values for those events.

For example, the following statements run ODS MARKUP with TYPE=EVENT_MAP to see which events and variables ODS uses for various parts of the PROC PRINT output:

 ods markup type=event_map file='custom-tagset-filename.xml';     proc print data=sashelp.class;        where Height gt 60;     run;     ods markup close;

Here is the listing output and resulting XML file:

Output 11.1: Listing Output

 The SAS System              1                               Obs     Name         Sex       Age       Height       Weight                                 1     Alfred        M         14        69.0         112.5                                 3     Barbara       F         13        65.3          98.0                                 4     Carol         F         14        62.8         102.5                                 5     Henry         M         14        63.5         102.5                                 8     Janet         F         15        62.5         112.5                                 9     Jeffrey       M         13        62.5          84.0                                12     Judy          F         14        64.3          90.0                                14     Mary          F         15        66.5         112.0                                15     Philip        M         16        72.0         150.0                                16     Robert        M         12        64.8         128.0                                17     Ronald        M         15        67.0         133.0                                19     William       M         15        66.5         112.0

Output 11.2: XML File

 <?xml version="1.0" encoding="windows-1252"?>  <doc operator="user" sasversion="9.1" saslongversion="9.01.01B0D06102003"        date="2003-06-11" time="15:55:02" encoding="windows-1252" event_name="doc"        trigger_name="attr_out" class="Body" index="IDX" just="c">    <doc_head event_name="doc_head" trigger_name="attr_out" class="Body"        index="IDX" just="c">      <doc_meta event_name="doc_meta" trigger_name="attr_out" class="Body"        index="IDX" just="c"/>      <auth_oper event_name="auth_oper" trigger_name="attr_out" class="Body"        index="IDX" just="c"/>      <doc_title event_name="doc_title" trigger_name="attr_out" class="Body"        index="IDX" just="c"/>      <stylesheet_link event_name="stylesheet_link" trigger_name="attr_out"        index="IDX" just="c"/>      <javascript event_name="javascript" trigger_name="attr_out" class="Body"        index="IDX" just="c">        <startup_function event_name="startup_function" trigger_name="attr_out"           class="StartUpFunction" index="IDX" just="c">        </startup_function>        <shutdown_function event_name="shutdown_function" trigger_name="attr_out"           class="ShutDownFunction" index="IDX" just="c">        </shutdown_function>      </javascript>    </doc_head>    <doc_body event_name="doc_body" trigger_name="attr_out" class="Body"        index="IDX" just="c">      <proc event_name="proc" trigger_name="attr_out" name="Print"        index="IDX" just="c">        <anchor event_name="anchor" trigger_name="attr_out" class="Body" name="IDX"           index="IDX" just="c"/>        <page_setup event_name="page_setup" trigger_name="attr_out" class="Body"           index="IDX" just="c">          <system_title_setup_group event_name="system_title_setup_group" trigger_name="attr_out"            class="Body" colcount="1" index="IDX" just="c">            <title_setup_container event_name="title_setup_container" trigger_name="attr_out"               class="SysTitleAndFooterContainer" colcount="1" index="IDX" just="c">              <title_setup_container_specs event_name="title_setup_container_specs" trigger_name="attr_out"                 class="SysTitleAndFooterContainer" colcount="1" index="IDX" just="c">                <title_setup_container_spec event_name="title_setup_container_spec" trigger_name="attr_out"                    colcount="1" type="string" index="IDX" just="c" width="100%"/>              </title_setup_container_specs>              <title_setup_container_row event_name="title_setup_container_row" trigger_name="attr_out"                 colcount="1" index="IDX" just="c">                <system_title_setup event_name="system_title_setup" trigger_name="attr_out"                    class="SystemTitle" value="The SAS System" colcount="1" index="IDX" just="c">                </system_title_setup>              </title_setup_container_row>            </title_setup_container>          </system_title_setup_group>        </page_setup>  ...more xml tagged output...                 </table_body>              </table>            </output>          </leaf>        </proc_branch>      </proc>    </doc_body>  </doc>

For example, in the XML output that is generated by EVENT_MAP, you can see that PROC PRINT uses events named DOC_HEAD, PROC, TABLE, and so on. The TABLE event uses data from event variables like STATE, CLASS, and TYPE. Once you know the events and variables that are used to generate the output, then you can define your own tagset definition and customize the events. For example, you could redefine the TABLE event to produce your own output.

To define a tagset to customize your own output, you could start by specifying TAGSETS.EVENT_MAP as the parent tagset. Then, as you redefine events to customize output, they will replace the default events defined in the EVENT_MAP tagset. In addition, you can remove the operation of a default event by redefining it as an empty event in your tagset definition. When you're satisfied with the customized output, remove the EVENT_MAP inheritance and the empty events. Then, your output will reflect only the events you defined.

Note: When you first run a SAS process and specify TYPE=EVENT_MAP, you can also generate a stylesheet along with the body file. The stylesheet will tell you which style attributes are being used.

Alternatives to EVENT_MAP

If you want other types of output, here are a few tagsets that you can use as alternatives:

TEXT_MAP generates more of a listing output.
TPL_STYLE_LIST (generates HTML) and TPL_STYLE_MAP (generates XML). However, these tagsets list only a subset of the possible attributes.
STYLE_POPUP generates HTML like HTMLCSS, but if you're using Internet Explorer, STYLE_POPUP displays a window that shows the resolved ODS style definition for any item that you click.
STYLE_DISPLAY is like STYLE_POPUP but generates a simple page of output for you to click.
NAMEDHTML generates HTML output like STYLE_POPUP but with all the objects labeled as with ODS TRACE.

Defining a Tagset Using SAS DATA Step Functions

A SAS DATA step function performs a computation or system manipulation on arguments and returns a value. In Base SAS software, you can use SAS functions in DATA step programming statements, WHERE expressions, macro language statements, the REPORT procedure, Structured Query Language (SQL), and when creating your own tagsets. Functions can be used on any statement within the tagset language. For information on DATA step functions and statements, see SAS Language Reference: Dictionary and SAS Language Reference: Concepts .