Add symbols and values to symbol table.

DOCUMENT SET
>>-DOCUMENT--SET--DOCTOKEN(data-area)--------------------------->
>--+-SYMBOL(name)--VALUE(data-area)-------------------+--------->
'-SYMBOLLIST(data-area)--+-----------------------+-'
'-DELIMITER(data-value)-'
>--LENGTH(data-value)--+-----------+---------------------------><
'-UNESCAPED-'
Conditions: NOTFND, SYMBOLERR
This command is threadsafe.
Description
DOCUMENT SET allows the application to add symbols and their associated
values to the symbol table. If the symbol being added already exists in the
table, it is replaced by the new definition.
Note: - When a template containing symbols has been inserted into a document,
you cannot change the substituted values of those symbols in the document
that is being composed. If you set different values for the symbols, the new
values 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.
- If you insert a template before the symbols contained in it are set, the
symbols will never be substituted. This can occur if you create a document
from a template without specifying a symbol list.
Options
- DELIMITER(data-value)
- specifies an optional 1–byte value used to delimit symbol name-value
pairs in the SYMBOLLIST buffer. If this option is not specified, the value
defaults to an ampersand. There are several disallowed DELIMITER values, all
of which cause an INVREQ condition if used. The disallowed values are:
- null (binary X'00')
- shift in (binary X'0E')
- shift out (binary X'0F')
- space (binary X'40')
- plus sign (binary X'4E')
- colon (binary X'7A')
- equals (binary X'7E')
- percent sign (binary X'6C')
- backslash (binary X'E0')
If this option is used, the application must ensure that the DELIMITER
does not appear in any symbol value in the SYMBOLLIST buffer. For this reason,
the application should not use alphanumeric and other printable characters
as the DELIMITER value.
- DOCTOKEN(data-area)
- specifies the 16-byte symbolic name of the document that owns the symbol
table.
- LENGTH(data-value)
- specifies the length, as a fullword binary value, of the buffer containing
the data value associated with the symbol, or the length of the buffer containing
the symbol list when the SYMBOLLIST option is used.
- SYMBOL(name)
- specifies the name of the symbol that is to be added to the
table. The name can be 1 to 32 characters in length with no embedded spaces.
The name of the symbol must contain only uppercase and lowercase letters,
numbers and the special characters dollar ('$'), underscore ('_'),
hyphen ('-'), number sign ('#'), period ('.') and at
sign ('@'). The name is case-sensitive, so uppercase letters are regarded
as different from lowercase letters. If you want to define more than one symbol
in the same command, use the SYMBOLLIST option instead.
- SYMBOLLIST(data-area)
- specifies a buffer which contains a symbol list. Use the
LISTLENGTH option to specify the length of this buffer. A symbol list
is a character string consisting of one or more symbol definitions separated
by ampersands. Each symbol definition consists of a name, an equals sign,
and a value. By default, symbols in the symbol list are separated
by the & character, but you can override this by using the DELIMITER keyword
to specify a different symbol separator. Here is an example of a symbol list:
applid=IYCQ&jobname=test
The following rules apply when
setting symbols using a SYMBOLLIST:
- The name is case-sensitive. It may only contain uppercase and lowercase
letters, numbers, and the special characters dollar ('$'), underscore
('_'), hyphen (-'), number sign ('#'), period ('.')
and at sign ('@'). The name is case-sensitive, so uppercase letters
are regarded as different from lowercase letters. Unlike the symbols in the
template, the names in the symbol list have neither an ampersand at the beginning,
nor a semicolon at the end. For example, the symbol &mytitle; in the template
corresponds to the name mytitle in the symbol list.
- The values in the symbol list can contain any characters. However, special
coding is required if you need to include the following characters in symbol
values in the symbol list:
- The character that you have used as the symbol separator (which defaults
to an ampersand, but can be overridden by use of the DELIMITER option).
- The plus sign and the percent sign.
You can use the percent sign, followed by two characters that are hexadecimal
digits (that is, 0–9, a-f, and A-F), to include characters such as these
that have a special meaning. When the value is put into the symbol table,
a percent sign and the two hexadecimal digits following it are interpreted
as the EBCDIC equivalent of the single ASCII character denoted by the two
digits. %2B produces a plus sign, %25 produces a percent sign,
and %26 produces an ampersand. If the characters following the percent
sign are not two valid hexadecimal digits, the percent sign and the following
characters are put into the symbol table as they appear in the symbol list.
If the UNESCAPED option is used, no conversion takes place, and all the characters
are put into the symbol table as they appear in the symbol list.
- If you want to include spaces in a value, CICS allows you to use the space
character, a plus sign, or an escape sequence (%20). However, you cannot use a plus sign or escape sequence to indicate a
space character when the UNESCAPED option is used. In this case, you must
only use a space character to indicate a space.
- UNESCAPED
- prevents CICS® from unescaping symbol values contained in the SYMBOLLIST
buffer. If this option is used, plus signs are not converted to spaces, and
sequences such %2B are not converted to single byte values.
The
UNESCAPED option does not allow you to include the character that you have
used as the symbol separator within a symbol value in a symbol list. If you
want to use the UNESCAPED option, choose a symbol separator that will never
be used within a symbol value. Alternatively, you can use the SYMBOL and VALUE
options to specify symbol values that contain the character you have used
as the symbol separator, because the symbol separator has no special meaning
when used in the VALUE option.
- VALUE(data-area)
- specifies an area containing the value to be associated with the SYMBOL.
The rules for including spaces in a symbol value in a symbol list
also apply to the VALUE option: you can use a simple space character or a
plus sign, unless the UNESCAPED option has been specified, in which case you
must use a space character. Also, the special coding that is required to include
a plus sign or percent sign in symbol lists is similarly required in the VALUE
option, unless the UNESCAPED option has been specified. However,
ampersands, or any other character that you have specified as a symbol separator
for the symbol list, have no special significance when used in the VALUE option.
Conditions
- INVREQ
- RESP2 values:
- 8
- The value specified for DELIMITER is not valid.
- NOTFND
- RESP2 values:
- 1
- The document has not been created or the name is incorrectly specified.
- SYMBOLERR
- a symbol name is invalid. RESP2 values:
- 0
- SYMBOLLIST was not used.
- offset
- RESP2 contains the offset of the invalid symbol in the list.