Your application can define values for symbols in a document
template
using the DOCUMENT SET command or the DOCUMENT CREATE command. The symbol
values are substituted when the template is used, either by a DOCUMENT
CREATE
command or by a DOCUMENT INSERT command.
About this task
You can define individual symbols using the SYMBOL and VALUE
options on the DOCUMENT SET command. Alternatively, you can define
several
symbols in a single command using the SYMBOLLIST option on the DOCUMENT
CREATE
or DOCUMENT SET command. By default, the symbol separator for the
symbol list
is an ampersand, but you can override this by using the DELIMITER
option on
the commands.
When you are designing your application, remember that:
- You must define values for the symbols before, or at the time
when, you
insert the document template into the document. You cannot change the
substituted
values of the symbols after the template has been inserted.
- Every symbol in a document template should be defined. If any
symbol in
the document template is not defined, either by the application
program or
by a #set command, no symbol substitution takes place for that
symbol, and
the finished document includes the symbol name or the #echo command
specifying
the symbol.
- A symbol definition provided by an application using the
DOCUMENT SET
command overrides a default value provided for the symbol by a #set
command.
- A symbol which has been assigned a value using the DOCUMENT SET
command
can be changed by issuing another DOCUMENT SET command. If you do
this after
the document template has been inserted into the document, the new
values
are placed into the symbol table, and they will be used the next time
that
the template is inserted into a document. Your changes will not
affect the
values that have already been inserted into the document.
Rules for specifying symbols and symbol lists
lists
the rules relating to symbol names, special characters and spaces in
symbol
values, and symbol list separator characters.
Procedure
- To define an individual symbol, use the DOCUMENT SET command
with
the SYMBOL and VALUE options. The SYMBOL option specifies the name
of the symbol, and the VALUE option specifies the value for that
symbol. Follow
the rules in
Rules for specifying symbols and symbol lists
. That topic explains the effects of the UNESCAPED
option.
- Make sure you issue the DOCUMENT SET command
before
you
issue the DOCUMENT INSERT command which places the document template
in the
document.
- You cannot use the DOCUMENT CREATE TEMPLATE command if you
need
to use DOCUMENT SET commands to set symbol values. Instead, you can
create
an empty document first, then define the symbol values with
DOCUMENT SET commands,
and then use the DOCUMENT INSERT command to insert the template that
contains
the symbol references.
- To provide a symbol list containing multiple symbol
definitions,
use the SYMBOLLIST option on the DOCUMENT CREATE or DOCUMENT SET
command. When you use TEMPLATE and SYMBOLLIST together on DOCUMENT
CREATE, the
symbols from the symbol list are resolved when the template is added to
the
document. If you are using the DOCUMENT SET command, make sure
you issue it
before
you issue the DOCUMENT INSERT command which places
the document template in the document.
- If the default symbol separator
&
(ampersand) is
not suitable, because you want to use that character in a symbol
value, use
the DELIMITER option to specify an alternative character.
Follow
the rules in
Rules for specifying symbols and symbol lists.
- Use the SYMBOLLIST option to specify a buffer which contains
the symbol list.
Specify each symbol definition, separated by
your chosen symbol separator. Symbols and symbol lists
shows an example of a symbol list. Follow the rules
in
Rules for specifying symbols and symbol lists.
That topic explains the effects of the UNESCAPED option.
- Use the LISTLENGTH option to specify the length of your
symbol
list.
Depending on your application, you might find that instead
of specifying the exact list length for your symbol list each time
you define
values for the symbols, it is more convenient to choose a permanent
value
for the LISTLENGTH option, which will provide a fixed list length
for your
symbol list. If you do this:
- The fixed list length that you choose should be long enough
to include
the maximum length of symbol list that you expect to supply.
- When your fixed list length is greater than the actual length
of the symbols
that you supply, include an extra dummy symbol at the end of your
symbol list,
such as
'&END='
. This avoids the possibility of trailing
spaces or unpredictable characters in the value of the last symbol in
the
list. Do not include this dummy symbol in any templates or
documents. Any
trailing spaces or unpredictable characters will be assigned to the
dummy
symbol and will not appear in your documents.
Results
The symbols that you define are placed into the symbol table.
If you
are defining a symbol list on the DOCUMENT CREATE command, symbol
substitution
takes place immediately, and the document is created using the document
template
and your specified symbols. If you are using the DOCUMENT SET command to
define
individual symbols or a symbol list, the values you have placed in the symbol
table are used for symbol substitution when a DOCUMENT CREATE or
DOCUMENT
INSERT command is issued using that document template.