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: INVREQ, LENGERR, 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. Certain delimiter values (such as the space character) are
disallowed, and all of these cause an INVREQ condition on the command if used.
They are listed in Rules for specifying symbols and symbol lists.
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 binary token 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. Rules for specifying symbols and symbol lists lists the rules which apply when specifying the name of a symbol.
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 LENGTH 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.Here is an example of
a symbol list:
applid=IYCQ&jobname=test
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. Rules for specifying symbols and symbol lists lists the rules which apply when setting symbols using a SYMBOLLIST.
- 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. Rules for specifying symbols and symbol lists lists the rules which apply when specifying the value of a symbol.
Conditions
- 16 INVREQ
- RESP2 values:
- 8
- The value specified for DELIMITER is not valid.
- LENGERR
- RESP2 value:
- 9
- The value specified for symbol list LENGTH is invalid. Value must be between
1 and (16M - 1).
- 10
- The value specified for symbol value LENGTH is invalid. Value must be
between 1 and (16M - 1).
- 13 NOTFND
- RESP2 values:
- 1
- The document has not been created or the name is incorrectly specified.
- 116 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.