DOCUMENT SET

Add symbols and values to symbol table.

Read syntax diagramSkip visual syntax diagram
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:
  1. 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.
  2. 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.