Defining symbol values

Your application can define values for symbols in a document template using the DOCUMENT SET command or the DOCUMENT CREATE command. The symbol values are substituted when the template is used, either by a DOCUMENT CREATE command or by a DOCUMENT INSERT command.

About this task

You can define individual symbols using the SYMBOL and VALUE options on the DOCUMENT SET command. Alternatively, you can define several symbols in a single command using the SYMBOLLIST option on the DOCUMENT CREATE or DOCUMENT SET command. By default, the symbol separator for the symbol list is an ampersand, but you can override this by using the DELIMITER option on the commands.

When you are designing your application, remember that:
  • You must define values for the symbols before, or at the time when, you insert the document template into the document. You cannot change the substituted values of the symbols after the template has been inserted.
  • Every symbol in a document template should be defined. If any symbol in the document template is not defined, either by the application program or by a #set command, no symbol substitution takes place for that symbol, and the finished document includes the symbol name or the #echo command specifying the symbol.
  • A symbol definition provided by an application using the DOCUMENT SET command overrides a default value provided for the symbol by a #set command.
  • A symbol which has been assigned a value using the DOCUMENT SET command can be changed by issuing another DOCUMENT SET command. If you do this after the document template has been inserted into the document, the new values are placed into the symbol table, and they 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.

Rules for specifying symbols and symbol lists lists the rules relating to symbol names, special characters and spaces in symbol values, and symbol list separator characters.

Procedure

  1. To define an individual symbol, use the DOCUMENT SET command 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. Follow the rules in Rules for specifying symbols and symbol lists . That topic explains the effects of the UNESCAPED option.
    1. Make sure you issue the DOCUMENT SET command before you issue the DOCUMENT INSERT command which places the document template in the document.
    2. You cannot use the DOCUMENT CREATE TEMPLATE command if you need to use DOCUMENT SET commands to set symbol values. Instead, you can create an empty document first, then define the symbol values with DOCUMENT SET commands, and then use the DOCUMENT INSERT command to insert the template that contains the symbol references.
  2. To provide a symbol list containing multiple symbol definitions, use the SYMBOLLIST option on the DOCUMENT CREATE or DOCUMENT SET command. When you use TEMPLATE and SYMBOLLIST together on DOCUMENT CREATE, the symbols from the symbol list are resolved when the template is added to the document. If you are using the DOCUMENT SET command, make sure you issue it before you issue the DOCUMENT INSERT command which places the document template in the document.
    1. If the default symbol separator & (ampersand) is not suitable, because you want to use that character in a symbol value, use the DELIMITER option to specify an alternative character. Follow the rules in Rules for specifying symbols and symbol lists.
    2. Use the SYMBOLLIST option to specify a buffer which contains the symbol list. Specify each symbol definition, separated by your chosen symbol separator. Symbols and symbol lists shows an example of a symbol list. Follow the rules in Rules for specifying symbols and symbol lists. That topic explains the effects of the UNESCAPED option.
    3. Use the LISTLENGTH option to specify the length of your symbol list. 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. If you do this:
      • The fixed list length that you choose should be long enough to include the maximum length of symbol list that you expect to supply.
      • When your fixed list length is greater than the actual length of the symbols that you supply, include an extra dummy symbol at the end of your symbol list, such as '&END=' . This avoids the possibility of trailing spaces or unpredictable characters in the value of the last symbol in the list. Do not include this dummy 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.

Results

The symbols that you define are placed into the symbol table. If you are defining a symbol list on the DOCUMENT CREATE command, symbol substitution takes place immediately, and the document is created using the document template and your specified symbols. If you are using the DOCUMENT SET command to define individual symbols or a symbol list, the values you have placed in the symbol table are used for symbol substitution when a DOCUMENT CREATE or DOCUMENT INSERT command is issued using that document template.


dfhp3_doc_symbol_values.html | Timestamp icon Last updated: Monday, 5 June 2017