The Current Version of This Document Is 1.0 DRAFT

SIML Language Definition

This is an introduction to the SIML (SAS/Internet Markup Language), explaining components, macros, templates, and so forth.

The current version of this document is 1.0 DRAFT.

Introduction

SIML is a markup language which allows rapid creation of certain SAS/Internet web pages.

SIML is principally designed by Ren Bauer of the SWHIG group with the assistance of Hye-Chung Kum

The purpose of this manual is to give document the language such that the reader can gain an understanding of the separate parts of the language, their interaction and respective capabilities.

SIML works in conjunction with two other languages, SAS/Internet and HTML. Files written in SIML are compiled in to both of these languages before displayed to the user. The following diagram gives a visual representation of how SIML files are converted to final output.

As such, code entered into an SIML file can be processed at any of three levels: The SIML, SAS/Internet, or HTML level. More detail on how code for each level should be written in the SIML file will be provided in following sections.

The main focus of this document will be on SIML to SAS/Internet compilation. In order to accommodate this, SIML utilizes three major components: Templates, external files, and SIML files. The following chart provides a visual representation of how these files are combined to produce one SAS/Internet file.

As such, the code present in the SAS/Internet file can be influenced by modifying any of these three components. The details of what is present in these and how they are used will be provided in following sections.

Templates

SIML creates full SAS/Internet web pages via the use of template files. Template files consist mainly of SAS/Internet code with special tags that allow SIML to insert code in specified areas. In this section we provide an overview of the template files, their purposes, and how to use them.

File name / Short name / Purpose
gratmpl.sas / gra / Area or line graphs
grptmpl.sas / grp / Pie or Bar charts
indextmpl.sas / index / Index pages
tabletmpl.sas / table / Table pages

In SIML code, the template file is specified in the first line of code via a start tag containing the template’s short name. For example, the following tag will specify the use of the grb template to create a bar chart.

grb

…

</grb

Each template file contains multiple sections in which code can be added. In the template files, these are specified by a special tag of the form ‘##S:SECTIONNAME’. To specify which section SIML code should be translated into, the user should place start and end tags as in the following code:

…

s:sectionname

…

</s:sectionname

…

In this code, anything within the section tags will be translated into SAS/Internet code and replace the ##S:SECTIONNAME tag in the specified template file. A description of available sections and their uses is given in a later section.

In addition, each template file contains a small amount of variable tags. These are tags that behave similarly to section tags, but are meant to be replaced by a short value, instead of a block of code. These tags are of the form ‘##VAR’, and are utilized as follows:

…

var> … </var

…

Here, the value between the var tags will replace any instance of the ##VAR tag in the template file. A description of available variables and their uses is given in a later section.

Finally, each template has a set of SAS Macro variables that can be utilized to specify exactly how the output file will work. These variables can be modified just like any other SAS Macro (see ‘modes’ section for more details), and this can be done in any section (see ‘sections’ section for more details). A full list of available macro variables is available in a later section.

External Common Files

SIML makes use of several external SAS/Internet files which are common between all template files via the use of %include statements. The following is a list of external files and what they contain.

File name / Contents
config.sas / StatCounter code and libname statements
menu.sas / Code to create top menu on web pages
multi_format.sas / Code to customize pages for html, pdf, or csv format
lib.sas / Pre-defined formats, axes, legends, colors, patterns, and select macros for use across pages.
config-common.sas / Macros and macro variables used across multiple pages, code for side menu, and symbol statements for use across pages.

These files are automatically included in the creation of any webpage. Use of the macros and variables they provide will be covered in a later section.

SIML Files

SIML files are the component written by the user. Commonly with an ‘xml’ extension, these files must adhere to strict xml syntax. However, as with most markup languages, SIML creates several special tags within the xml language. These tags fall into a few distinct categories.

Tag Type / Use / Location
Template tag / Specify the template file to use / First tag
Mode tag / Specify the SIML Mode with which the contained code should be treated / Anywhere
Variable tag / These tags apply a value to a specific variable within a template / Anywhere
Section tag / Specify the section within the template to which contained code should be translated / Anywhere

Using these tags, SIML code is generally laid out using one or both of the following manners:

template>
<variable>
…
</variable
<section1>
<mode>
…
</mode>
</section1>
<section2>
<mode>
…
</mode>
</section2>
</template>
/ template>
<variable>
...
</variable>
<mode>
<section1>
…
</section1>
<section2>
…
</section2>
</mode>
</template

Note that although an SIML file can contain multiple modes, sections, and variable tags, it can only contain one template tag and it must be the first.

Descriptions of available variable, section, and mode tags will be covered in later sections.

Generation Engine

The Generation Engine is a PHP app that parses the SIML and template files in order to combine them such that an operational SAS/Internet file is output. The current version of the Generation Engine is called allSpark.php, and is utilized from the command line using the following arguments:

Argument / Acceptable values / Purpose
site / work, priv, dev / Specify which version of the website for which the created SAS/Internet file should be configured.
input / any SIML file / Specify the SIML file which should be parsed as input.
output / any SAS/Internet file / Specify the SAS/Internet file which should be created or overwritten as output.
template / any template file, any directory, or no argument / Specify where to find the template file which should be parsed as input.

Via the following syntax:

allspark.php [site] [input SIML file] [output SAS/Internet file] -[template file/directory]

Note that the template file argument is optional. This is because the SIML language can usually determine the name of the template file from the information provided in the SIML code, and assumes that all template files are placed in a specified directory beneath the runtime location. The following table lists acceptable entries for the template argument, and the file that will be opened as the template. Here, ‘SIML’ will denote the contents of the template tag within the SIML file.

Entry / File opened as template
Blank / template/SIMLtmpl.sas
Directory/ / Directory/SIMLtmpl.sas
Directory/file.ext / Directory/file.ext

Comments

Because SIML files are translated to multiple files before final output is created, there are multiple ways to comment sections of code. The effects of these various forms of comments are realized at different levels of processing. The following table lists the types, provides an example, and explains the usage.

Comment Level / Examples (key Char) / Use
SIML / ##<S:VARDEF> (##)
##%LET nums=3 (##) / Comment at the SIML level, so the code is never present in the SAS/Internet output file, and does not affect the way the conversion engine is processing data.
Note the special character must be at the beginning of the line, and the whole line will be ignored.
SAS / *if car=3 then; (*)
% commeeent! (%) / Comment at the SAS/Internet level. This code is copied to the output file, but then is not processed by the SAS compiler, so is not present in the final HTML file displayed by a browser.
See SAS documentation for more details
HTML /  (<!--) / Comment at the HTML level. This code will make it all the way to the final HTML output displayed by a browser, but the browser will ignore it.
See HTML documentation for more details.

Sections

Each template contains several key tags which can be referenced through SIML, allowing instructions to be placed in different parts of the program. These tags are called “sections.” However, not all templates contain the same sections. The following table lists sections provided with SIML, the templates to which they apply, and their common uses.

Section / Template(s) / Use
VARDEF / All / Define SAS macro variables *
ADDMACROS / All / Define additional SAS macros *
GETDATA / All except index / Add SAS logic dealing with the obtainment of data
PROCDATA / All except index / Add SAS logic dealing with the processing of data
AXISLEG / All graphs / Define SAS Axes, Legends, Colors, or Patterns
LONGLABELS / All except index / Define labels to be displayed in column headers
ADDGRAPH / Line Graph / Add SAS logic to produce additional graph(s)
ADDTABLE / Line Graph / Add SAS logic to produce additional table(s)
JSCRIPT / Index / Add Javascript to be placed in the HTML header
HEADER / Index / Additional statements for the HTML header
BODY / Index / Add HTML body contents
ABOVETABLETXT / Table / Add text to be displayed above the table
BELOWTABLETXT / Table / Add text to be displayed below the table
OUTCODE / Table / Add SAS logic to produce additional output

*SAS Macro logic not allowed

For more information on how to use sections, see the ‘Templates’ section of this document. Note sections can be used in any order, and SAS Macro logic can be used in any section unless specified. See ‘Template’ section for more information on how to use sections.

Context Variables

Each template contains a few short context variables that are set directly via SIML. These context variables should be utilized in the creation of all files. The following table lists the context variables and their uses.

Variable / Set Type / Use
BY / Manual / Name the programmer who wrote the SIML file
SITE / Manual / Specify the set for which the SAS/Internet output file should be configured: (cw fs wf ma)/(work priv dev )
ST / Automatic / Specify the section of the site (cw fs wf ma)
DATE / Automatic / Date the output file was generated
NAME / Automatic / Specify the name of the SIML file used in generation

See ‘Template’ section for more information on how to use context variables.

Modes

Modes are they key tags within SIML which affect the way code within them is treated. The following code samples show the use of mode tags:

<code> *mode tag

if type=3 then do *\

year=2001 * -- affected content

end */

</code> *end mode tag

mode tag end mode tag

<by> Ren Bauer </by>

affected content

Below is a table listing the available SIML modes, and how they affect the contents within the start and end tags.

Mode / Affect / Example
EXPLANATION / Content is parsed and formatted for both HTML and PDF display, automatically placed under the appropriate section tag
In this mode, blank lines are preserved. Additional blank lines can be specified using the HTML <br/> tag. Other formatting such as italics and bold are not allowed. / <explanation>
This graph shows the …
*CI = Confidence Interval
</explanation>
SA / Content is parsed and modified to create a “SAS Anchor,” a link that result in the processing of a SAS/Internet program when clicked.
When using this tag, the href attribute must specify the name of the SAS program, and any urlparams excluding:
Format / County
Label / Entry
Content between tags are formatted for HTML / <sa href=”grpmap.sas&type=3”>
Map of things </sa>
SFORM / Content is parsed and modified to create a “SAS FORM,” a form that will result in the processing of a SAS/Internet program when submitted.
Content between tags are formatted for HTML
NOTE: sforms should generally be submitted via the sendForm() Javascript function, which checks to ensure a radio button is selected (if there are any), and if there is more than one dropdown box, the same value is not selected in multiple. / <sform submit=”grpmap.sas”>
<input type=”…
…
</input>
<input type=”button” onClick=”sendForm(doc…
</input>
</sform>
DROPDOWN / Content is parsed and an HTML select box is created. Adds ability to parse options submitted via the “value” attribute to create long lists of similar items. Following is a list of possible values:
Value / Options Generated
“sfy 2009 to 2007” / SFY 08-09
SFY 07-08
…
SFY 98-99
“period 2009_4 to 2007_1” / Oct 2009 – Sep 2010
Jul 2009 – Jun 2010
Apr 2009 – Mar 2010
Jan 2009 – Dec 2009
Oct 2008 – Sep 2009
…
Jan 2007 – Dec 2007
“Month January to December” / January
February
March
…
December
“qtr 2009_4 to 2007_1” / 2009 qtr 4
2009 qtr 3
…
2007 qtr 1
“quarter 1 to 8” / Quarter 1
Quarter 2
….
Quarter 8
“cohorts 2009 to 2007” / 2009 Cohorts
2008 Cohorts
2007 Cohorts
/ <dropdown name=”yr” value=”year 2009 to 1998” selected=”2004”
<option val=”…
</option>
</dropdown>
URLPARAMS / Contents are used as a list of URL parameters to be passed when a user changes pages, separated by commas and spaces. / <urlparams>type, byvar, year</urlparams>
VARIABLES / Contents are parsed as SAS macro variable declarations, such that each start/end tag pair become a SAS macro variable of the same name, and holding the contents between the tags as its value.
Any value can be used within these tags, but it is generally not recommended to use additional mode tags. / <YEAR>2001</YEAR>
<COUNTY>North Carolina </COUNTY
CODE / Contents are parsed as SAS/Internet code and not modified at all.
Any valid SAS/Internet function can be placed within this code. Unless otherwise stated under sections information, macro logic is also allowed. Any SIML start/end tags within the code tags will be treated as SAS/Internet code and will likely cause an error. The SAS/Internet ‘put’ function can also be used to place what will be treated as HTML code.
NOTE: By convention, ‘where’ statements are not allowed in this section. / <code>
%if year=2001 %then %do;
&county=North Carolina;
%end;
If month=Jan;
HTML / Contents are parsed as HTML code and formatted be correctly displayed in the HTML document.
See SFORM and SA for more information on how to write relevant HTML via SIML. / <html>
<h1>HEADER!</h1>
This text will be displayed on the web page! </html>

For more detailed information on modes, see the SIML technical document.