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)
- HMTL 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 formsnumeric 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:
- 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, 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.