DOCUMENT SET

Add symbols and values to symbol table.

DOCUMENT SET

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.