Setting symbol values

You can define values for symbols using the DOCUMENT SET command or the DOCUMENT CREATE command.

The DOCUMENT CREATE and DOCUMENT SET commands both take a SYMBOLLIST operand which allows several symbols to be defined in a single command. The SYMBOLLIST operand is a character string consisting of one or more definitions with single byte separators. By default, the symbol separator is an ampersand, but you can override this by using the DELIMITER option of the DOCUMENT SET or DOCUMENT CREATE commands. A definition for a symbol consists of a name, an equals sign, and a value.

This example defines three symbols. The first symbol called "title" has the value 'New Authors'. The second symbol called "author" has the value 'Halliwell Sutcliffe' and the last symbol called "editor" has the value 'Stanley Weyman'. To adhere to the specification for the content type application/x-www-form-urlencoded, plus signs have been used to indicate spaces within the symbol values; they will be converted to spaces when the symbol values are put into the symbol table.

•

The name of each 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.

•	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).

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. Some useful combinations are as follows:

•	If you want a plus sign in the value in the symbol table, put %2B in the value in the symbol list.

•	If you want a percent sign in the value in the symbol table, put %25 in the value in the symbol list.

•	If you want an ampersand in the value in the symbol table, put %26 in the value in the symbol list.

•	You can also use this coding to specify a space in the value in the symbol table--put %20 in the value in your symbol list. Alternatively, you can use the space character or the plus sign, as described below.

If you prefer not to use this special coding, you can specify the UNESCAPED option on the DOCUMENT CREATE or DOCUMENT SET command. When you specify this option, no conversion takes place, and the symbol values are put into the symbol table exactly as you entered them. The example below shows you how to do this. However, 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 on the DOCUMENT SET command 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.

If you want to include spaces in a value, XCICS allows you to use the space character. However, to adhere more closely to the specification for the content type, it is suggested that you use a plus sign instead of a space character. The plus sign is interpreted as a space when the symbol value is put into the symbol table. However, you cannot use a plus sign to indicate a space character when the UNESCAPED option is used to prevent XCICS from unescaping symbol values contained in a symbol list or in the VALUE option. In these cases, you must use a space character to indicate a space, because plus signs are not converted to spaces when the UNESCAPED option is used.

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. The fixed list length that you choose should be long enough to include the maximum length of symbol list that you expect to supply. However, on those occasions when the fixed list length that you have specified for your symbol list is greater than the actual length of the symbols that you supply, you might find that there are trailing spaces or unpredictable characters in the value of the last symbol in the list. You can avoid this issue by including an extra dummy symbol at the end of your symbol list, such as '&END='. Do not include this 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, so you can continue to specify a list length that is greater than the actual length of the symbols.

As an alternative to using a symbol list, the DOCUMENT SET command allows you to set individual symbol values 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. 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 of the DOCUMENT SET command 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 of the DOCUMENT SET command 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.