Substitution Syntax

A substitution statement within the <SASINSERT> opening tag and the </SASINSERT> closing tag inserts data from the specified package entry into a viewer file for delivery as HTML or text output

Syntax

Details

Specifying Values for the NESTED and ENTRY Attributes

Identifying an Entry by Its Order in the Package

Identifying an Entry by Filtering the Package

Example

Syntax

<SASINSERT> $(nested=z entry=x attribute=value)</SASINSERT>

Required Arguments

$( ): indicates the start of substitution mode using the dollar sign ($) followed by the open parenthesis. The close parenthesis indicates the end of substitution mode.

nested=z: identifies the nested package within the main package that is to be involved in the substitution. If the NESTED attribute is not specified, then only the entries in the main package are involved in the substitution. For information about the syntax of the z value, see Specifying Values for the NESTED and ENTRY Attributes.

entry=x: identifies the entry within the specified package that is to be targeted for the substitution. For information about the syntax of the x value, see Specifying Values for the NESTED and ENTRY Attributes.

name=someName

identifies a name of a name/value pair. The value of this name/value pair will be substituted. The name= and attribute= keywords cannot be specified on the same substitution string.

If entry= is specified along with name=, the entry's name/value specification will be used to make the substitution. For example, the following substitution takes the first entry in the package and determines the value of the name "title". This value is inserted into the HTML or text output:

$(entry=1 name="title")

This example evaluates the name/value that is specified at the main package level. The value for the name "title" is substituted:

($name="title")

attribute=value

identifies the attributes of the specified entry that are to be inserted into the HTML or text output. The value that is associated with this attribute can be any of the following:

description

inserts the description of the specified entry. For example, the following substitution inserts the description of the specified entry into the HTML or text output:

$(entry=1 attribute=description)

stream

streams the specified entry into the HTML or text output. The streamed entry must be one of the following entry types:

reference string (added to the package with the INSERT_REFERENCE CALL routine)
text file (added with INSERT_FILE routine)
binary file (added with INSERT_FILE routine)
HTML file (added with INSERT_HTML routine).

For example:

$(entry=1 attribute=stream)

reference

inserts a reference by substituting the entry's filename into the rendered view. For example, the following substitution inserts the filename of the first entry:

$(entry=1 attribute=reference)

abstract

Insert the package abstract at this location. If the NESTED attribute is not specified, the abstract of the main package is inserted in the HTML or text output. If the NESTED attribute is specified, then the abstract of the nested package is inserted in the HTML or text output. The ENTRY attribute is not valid when the abstract attribute is specified. For example, the following substitution inserts the main package abstract into the HTML or text output:

$(attribute=abstract)

Details

Specifying Values for the NESTED and ENTRY Attributes

The NESTED and ENTRY attributes are used in substitution syntax within the <SASINSERT> tag and as attributes on the <SASTABLE> tag. The examples that appear in this section apply to substitution syntax within the <SASINSERT> tag, but all of the syntax rules also apply to the use of the NESTED and ENTRY attributes in the <SASTABLE> tag.

You can specify the values of the NESTED and ENTRY attributes in two forms, numeric or name/value.

Note: Variable substitution is another type of substitution. It must be specified within the <SASTABLE> tag.

Identifying an Entry by Its Order in the Package

You use the entry's numerical order in the package to identify which entry is to be involved in a substitution operation.

An example of package entry order follows:

SAS data set
binary file
reference string
HTML file

The SAS data set is the first entry, the binary file is the second entry, and so on.

For the NESTED attribute, a numeric value identifies the package that is involved in the substitution based on order of nesting into the package. For example, nested=3 specifies the third package that is nested in the main package. To accommodate packages with multiple levels of nesting, a period (.) differentiates levels of nesting. For example, nested=2.5 specifies the fifth package that is nested in the second package that is nested in the main package.

For the ENTRY attribute, a numeric value identifies the entry that is to be used in the substitution that is based on the order of insertion into the package. For example, $(entry=2) specifies the second entry in the package.

If the NESTED attribute is not specified, then the specified entry in the main package is used for the substitution.

Identifying an Entry by Filtering the Package

Name/value pairs are used in the NESTED and ENTRY attributes to specify filters that determine which nested packages and entries are to be involved in a substitution operation. You must quote the name/value pair and contain it within parentheses. For example,

$(nested="(type=report)" entry="(a=b)")

When the name/value pair is specified outside the <SASREPEAT> tags, only the first entry that matches the filter is substituted. When the name/value pair is used inside the <SASREPEAT> tags, all entries that match the filter are substituted into the HTML or text output.

To limit the search for an entry to the main package only, omit the NESTED attribute. For example, $(entry="(type=report)") specifies that the entry that is to be involved in the substitution operation is the first entry in the main package that has a name/value pair of type=report.

Entries in the main package are always candidates for name/value substitution, even when the NESTED attribute is specified. In the following example, the entry that is involved in the substitution is either the first entry in the main package that matches the a=b name/value pair or it is the first entry that matches a=b in the first nested package with the type=report name/value pair.

$(nested="(type=report)" entry="(a=b)")

To substitute all entries that match the name/value pairs, enclose the substitution within the <SASREPEAT> tag. If the preceding example were enclosed in <SASREPEAT> tags, the entries that are involved in the substitution would be all those in the main package and the nested packages that match the a=b name/value pair.

The name/value syntax also supports the asterisk (*) wildcard on the NESTED attribute. The asterisk indicates "all levels below." For example, to substitute "all entries in all nested packages beneath this level," use a period (.) and an asterisk (*) in the NESTED attribute, as follows:

$(nested="(type=report).*" entry="(a=b)")

The preceding example identifies for the substitution all entries that match the a=b name/value pair in the following packages:

the main package
the first nested package that contains a match of the type=report name/value pair, regardless of the nesting level of that package
any package, regardless of name/value pair, that is nested beneath the first nested package

To substitute all matching entries in the main package and in all nested packages, use an asterisk in the NESTED attribute, as shown in the following example:

$(nested="*" entry="(a=b)")

The preceding example substitutes all entries in the main package and in all nested packages at any level that match the name/value pair a=b.

Example: Using Substitution Syntax

$(entry=1 attribute=description)

indicates that the description for package entry 1 is to be substituted at this location.

$(nested=1 entry=4 attribute=stream)

indicates that the fourth entry within the first nested package should be streamed at this location. The entry must be either a reference, a text file, a binary file, or an HTML file.

$(nested=1.2 entry=2 attribute=stream)

identifies for streaming the second entry in the second package that is nested in the first package that is nested in the main package.

$(nested="*" entry="(type=report)" attribute=description)

indicates that the description of the first entry within the main package, or any nested packages, that matches the type=report name/value pair is to be substituted into the HTML or text output. If the substitution is contained within <SASREPEAT> tags, then all entries in the main and nested packages that match the type=report name/value pair are substituted into the HTML or text output.

$(nested="(type=report)" attribute=abstract)

indicates that the abstract from the nested package within the main package that matches the type=report name/value pair is to be substituted into the HTML or text output. If this substitution were specified within <SASREPEAT> tags, then the abstracts of all matching nested package entries in the main package are inserted into the HTML or text output.

$(name=title entry=1)

indicates that the first entry in the package is used for the substitution. Because name= is specified, a name/value substitution occurs. Name= identifies the name of a name/value pair. Therefore, in this case, it indicates a name of title. If the first entry's name/value specification contains a name of title, its value is substituted.

$(name=Definition entry="(type=report)")

indicates that the substitution occurs for the first entry within the main package that has the type=report name/value pair. The name= syntax indicates that a name/value substitution occurs. If the entry that matches the type=report filter has a name/value pair with the name of Definition, then its value is substituted. If this substitution is contained in a <SASREPEAT> tag, then the name/value substitution will occur for all entries in the main package that match the type=report filter.

$(name=title)

indicates that because entry= is not used in this substitution string, the name/value for the main package is used for the substitution. Name= identifies the name of a name/value pair, so in this case it indicates a name of title. If the package's name/value specification contains a name of title, then its value is substituted.