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

To specify a substitution, use the following syntax within the <SASINSERT> tag:

   $(nested=z entry=x attribute=value)

The attributes of the SASINSERT substitution are defined as follows:

$(  )

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, 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 file name into the rendered view. For example, the following substitution inserts the file name 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, 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)

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

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.

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:

1. SAS data set
2. binary file
3. reference string
4. 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, 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 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.

Examples

$(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, all entries in the main and nested packages that match the type=report name/value pair would be 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, the abstracts of all matching nested package entries in the main package would be inserted into the HTML or text output.

$(name=title entry=1)

indicates that the first entry in the package will be used for the substitution. Because name= is specified, a name/value substitution will occur. 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 will be substituted.

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

indicates that the substitution will occur for the first entry within the main package that possesses the type=report name/value pair. The name= syntax indicates that a name/value substitution will occur. If the entry that matches the type?report filter has a name/value pair with the name of Definition, its value will be substituted. Note that if this substitution is contained in a <SASREPEAT> tag, 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 will be 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, its value will be substituted.