Programming with documents and document templates

This section covers the following topics:

Symbols and symbol lists

Symbols represent variable data that is resolved at the time the template is added to the document - at the time the DOCUMENT CREATE or DOCUMENT INSERT is issued.

The application program needs to define values for the symbols that will be substituted when the template is used. These values can be defined on the DOCUMENT CREATE or the DOCUMENT SET commands. These commands both take a SYMBOLLIST operand which allows several symbols to be defined in a single command. You can also define individual symbols by using the SYMBOL and VALUE operands on the DOCUMENT SET command.

When you are planning your use of symbols and templates, note that:

  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.
  3. Symbol substitution does not occur in html comments.

The support for symbols and symbol lists in the DOCUMENT application programming interface is designed to interpret data with a content type of application/x-www-form-urlencoded, as described in the HTML specification (at http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4). This is the format in which data is returned when it has been entered into a form on a web page.

In CICS®, the DOCUMENT application programming interface extends this specification in respect of space characters. You can use simple space characters to indicate spaces within values in a symbol list or in the VALUE option; you do not have to use a plus sign to indicate a space. However, if you want to adhere more closely to the specification, it is suggested that you do use a plus sign instead of a space character when possible. Note, though, that you cannot use a plus sign to indicate a space character when the UNESCAPED option is used to prevent CICS 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.

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.

Here is an example of a symbol list:

  mytitle=New+Authors&auth1=Halliwell+Sutcliffe&auth2=Stanley+Weyman

This example defines three symbols. The first symbol called mytitle has the value 'New Authors'. The second symbol called auth1 has the value 'Halliwell Sutcliffe' and the last symbol called auth2 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 following rules apply when setting symbols using a SYMBOLLIST:

The following example shows you how, without using special coding, you can pass symbol values to the document handler containing embedded plus signs, percent signs, and ampersands, none of which are to undergo unescape processing:

EXEC CICS DOCUMENT CREATE
          DOCTOKEN(ATOKEN)
          DELIMITER('!')
          SYMBOLLIST('COMPANY=BLOGGS & SON!ORDER=NUTS+BOLTS')
          LISTLENGTH(37)
          UNESCAPED			

Here the symbol COMPANY has a value of 'BLOGGS & SON', and the symbol ORDER has a value of 'NUTS+BOLTS'. The symbol separator used in this example is '!', but it is best to use a non-printable character that does not appear in the symbol value. The use of a character other than the ampersand as the symbol separator means that an ampersand can be used in 'BLOGGS & SON'. The use of the UNESCAPED option ensures that the plus sign in 'NUTS+BOLTS' does not get converted to a space. Because the UNESCAPED option has been used, you must use a space character, rather than a plus sign, to indicate where a space is required in the symbol value, and the data no longer conforms to the specification for the content type application/x-www-form-urlencoded.

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.

Embedded template commands

The Document Handler recognises three commands that can be embedded in the template. These commands follow the syntax rules for Server Side Include commands. A Server Side Include command starts with the characters left angle bracket, exclamation mark, hyphen, hyphen, number sign followed by the command and it is terminated with the characters hyphen, hyphen, right angle bracket. For example:

<!--#command -->

The characters used to start and end the Server Side Include must be in codepage 037, otherwise the command will be ignored. The hexadecimal equivalents for these character sequences are X'4C5A60607B' and X'60606E'.

The three commands that are supported are #set, #echo and #include.

#set

The #set command is used to set the values of symbols and is useful for setting up default values for symbols. The #set command in the template will be ignored if the symbol has already been given a value using the DOCUMENT SET command. If a previous #set command has been used to assign a value to the symbol, the value will be overridden. A symbol which has been assigned a value using the DOCUMENT SET command can only be changed by issuing another DOCUMENT SET command.

#echo

The #echo command identifies a symbol that must be substituted when the template is inserted into the document. The string containing the #echo command will be completely replaced by the value associated with the symbol. If no symbol has been defined with that name, the #echo command will remain in the output data.

An alternative method to using the #echo command is to specify the symbol name, preceding it with an ampersand and terminating it with a semicolon. If we set a symbol called ASYM and give it a value of 'sample', the following two templates will give the same result after substitution.

Template 1:
   This is an example template.
   <!--#set var=ASYM value='sample'-->
   This is a <!--#echo var=ASYM--> symbol.

Template 2:
   This is an example template.
   <!--#set var=ASYM value='sample'-->
   This is a &ASYM; symbol.

Result of substitution:
   This is an example template.
   This is a sample symbol.
#include

The #include command allows a template to be embedded within another template. Up to 32 levels of embedding are allowed.

For example:

<!--#include template=templatename-->

wheretemplatename is the name of the template (the 48 byte name) defined in the doctemplate definition. The template name can also be enclosed in double quotes.

Using templates in your application

If you have created a template and defined it to CICS, the following example shows how you can use the template to create the contents of a document. The following template is created and defined to CICS with the name ASampleTemplate.

<!--#set var=ASYM value='DFLTUSER'-->
This is a sample document which has been created by user
<!--#echo var=ASYM-->.

In the application program, you can define a 48-byte variable called TEMPLATENAME and initialize it to a value of 'ASampleTemplate'. Once again you must define a 16-byte field for the document token (in this example, ATOKEN). You can then issue the command to create the document.

EXEC CICS DOCUMENT CREATE
          DOCTOKEN(ATOKEN)
          TEMPLATE(TEMPLATENAME)

This will result in a document being created with the content " This is a sample document which has been created by user DFLTUSER.".

To change the symbol to another value, you can issue the DOCUMENT CREATE command with the SYMBOLLIST option:

EXEC CICS DOCUMENT CREATE
          DOCTOKEN(ATOKEN)
          TEMPLATE(TEMPLATENAME)
          SYMBOLLIST('ASYM=Joe Soap')
          LISTLENGTH(13)

This will result in a document being created with the content "This is a sample document which has been created by user Joe Soap.".

The lifespan of a document

Documents created by an application exist only for the length of the CICS task in which they are created. This means that when the last program in the CICS task returns control to CICS, all documents created during the task’s lifetime are deleted. It is the application’s responsibility to save a document before terminating if the document is going to be used in another task. You can obtain a copy of the document by using the DOCUMENT RETRIEVE. The application can then save this copy to a location of its choice, such as a temporary storage queue. The copy can then be used to recreate the document.

The following sequence of commands show how a document can be created, retrieved and stored on a temporary storage queue, assuming that the following variables have been defined and initialised in the application program:

EXEC CICS DOCUMENT CREATE
          DOCTOKEN(ATOKEN)
          TEXT('A sample document.')
          LENGTH(18)

EXEC CICS DOCUMENT RETRIEVE
          DOCTOKEN(ATOKEN)
          INTO(DOCBUF)
          LENGTH(FWORDLEN)
          MAXLENGTH(20)

EXEC CICS WRITEQ TS
          QUEUE('AQUEUE')
          FROM(DOCBUF)
          LENGTH(HWORDLEN)

You can now use the following sequence of commands to recreate the document in the same or another application.

EXEC CICS READQ TS
          QUEUE('AQUEUE')
          INTO(DOCBUF)
          LENGTH(HWORDLEN)

EXEC CICS DOCUMENT CREATE
          DOCTOKEN(ATOKEN)
          FROM(DOCBUF)
          LENGTH(FWORDLEN)

When the document is retrieved, the data that is delivered to the application buffer is stored in a form which contains control information necessary to reconstruct an exact replica of the document. The document that is created from the retrieved copy is therefore identical to the original document. To help the application calculate the size of the buffer needed to hold a retrieved document, each document command which alters the size of the document has a DOCSIZE option. This is a fullword value which gives the maximum size that the buffer must be to contain the document when it is retrieved. This size is calculated to include all the control information and data. The size should not be taken as an accurate size of the document as the actual length delivered to the application can often be slightly smaller than this size. The length delivered will however never exceed the length in the DOCSIZE option.

The above example introduced the use of the FROM option on the DOCUMENT CREATE command. The data passed on the FROM option was the buffer returned to the application when the DOCUMENT RETRIEVE command was issued. It is possible for the application to supply data on the FROM option that did not originate from the DOCUMENT RETRIEVE command. When this happens, the document handler treats the data as a template and parses the data for template commands and symbols.

Retrieving the document without control information

The document data containing control information is only useful to an application that wishes to recreate a copy of the original document. It is possible to issue a DOCUMENT RETRIEVE command and ask for the control information to be omitted. The following command sequence uses the DATAONLY option on the DOCUMENT RETRIEVE command to instruct the Document Handler to return only the data. This example assumes that the following variables have been defined and initialised in the application program:

EXEC CICS DOCUMENT CREATE
          DOCTOKEN(ATOKEN)
          TEXT('A sample document.')
          LENGTH(18)

EXEC CICS DOCUMENT RETRIEVE
          DOCTOKEN(ATOKEN)
          INTO(DOCBUF)
          LENGTH(FWORDLEN)
          MAXLENGTH(20)
          DATAONLY

When the commands have executed, the buffer DOCBUF will contain the string "A sample document.".

Constructing a document

Once a document has been created, the contents can be extended by issuing one or more DOCUMENT INSERT commands. The options on the DOCUMENT INSERT command work in the same way as the equivalent commands on the DOCUMENT CREATE command.

The following sequence of commands shows an empty document being created followed by two INSERT commands:

EXEC CICS DOCUMENT CREATE
          DOCTOKEN(ATOKEN)

EXEC CICS DOCUMENT INSERT
          DOCTOKEN(ATOKEN)
          TEXT('Sample line 1. ')
          LENGTH(15)

EXEC CICS DOCUMENT INSERT
          DOCTOKEN(ATOKEN)
          TEXT('Sample line 2. ')
          LENGTH(15)

The document resulting from the above commands will contain:

Sample line 1. Sample line 2.

You can use the DOCUMENT RETRIEVE and DOCUMENT INSERT commands to insert a whole document into an existing document. The following variables must first be defined and initialized in the application program:

The following sequence of commands shows a document indicated by RTOKEN being inserted into another document indicated by ITOKEN:

 EXEC CICS DOCUMENT RETRIEVE       
           DOCTOKEN(RTOKEN)        
           INTO(DOCBUF)            
           LENGTH(RETRIEVLEN)      
           MAXLENGTH(MAXLEN)       
                                   
 EXEC CICS DOCUMENT INSERT         
           DOCTOKEN(ITOKEN)        
           FROM(DOCBUF)            
           LENGTH(RETRIEVLEN)      
                                   

The retrieved document is inserted at the end of the document specified in the DOCUMENT INSERT command, and all the control information of the retrieved document will be present in the second document. The LENGTH parameter of the DOCUMENT INSERT command must be equal to the value returned from the DOCUMENT RETRIEVE command into the field RETRIEVLEN.

The DOCUMENT INSERT command allows an operand called SYMBOL to be used to add blocks of data to the document. SYMBOL must contain the name of a valid symbol whose value has been set. The Document Handler inserts the value that is associated with the symbol into the document.

Note that when a value associated with a symbol has been inserted into a document, you cannot change that value in the document that is being composed. If you set a different value for the symbol, the new value will be used the next time that symbol is inserted into a document. Your change will not affect the value that has already been inserted into the document.

Using Bookmarks

The sequence in which an application inserts data into a document might not reflect the desired sequence that the data should appear in the document. Bookmarks allow the application to insert blocks of data in any order yet still control the sequence of the data in the document. A bookmark is a label that the application inserts between blocks of data. Note: a bookmark cannot be inserted in the middle of a block of data.

The following example creates a document with two blocks of text and a bookmark:

EXEC CICS DOCUMENT CREATE
          DOCTOKEN(ATOKEN)
          TEXT('Pre-bookmark text. ')
          LENGTH(19)

EXEC CICS DOCUMENT INSERT
          DOCTOKEN(ATOKEN)
          BOOKMARK('ABookmark       ')

EXEC CICS DOCUMENT INSERT
          DOCTOKEN(ATOKEN)
          TEXT('Post-bookmark text. ')
          LENGTH(20)

The document will now contain:

      Pre-bookmark text. <ABookmark>Post-bookmark text.

Note that the text <ABookmark> does not appear in the document content but serves merely as a pointer to that position in the document. To add data to this document, you can insert text at the bookmark as follows:

EXEC CICS DOCUMENT INSERT
          DOCTOKEN(ATOKEN)
          TEXT('Inserted at a bookmark. ')
          LENGTH(25)
          AT('ABookmark       ')

Logically, the data of the document will contain the following (Note that in this instance, only the data is being shown and not the position of the bookmark).

Pre-bookmark text. Inserted at a bookmark. Post-bookmark text.

If the AT option is omitted, the data is always appended to the end of the document. A special bookmark of 'TOP' can be used to insert data at the top of the document, making it unnecessary to define a bookmark which will mark the top of the document.

Replacing data in the document

The following example shows how data between two bookmarks can be replaced:

EXEC CICS DOCUMENT CREATE
          DOCTOKEN(ATOKEN)

EXEC CICS DOCUMENT INSERT
          DOCTOKEN(ATOKEN)
          TEXT('Initial sample text. ')
          LENGTH(21)

EXEC CICS DOCUMENT INSERT
          DOCTOKEN(ATOKEN)
          BOOKMARK('BMark1          ')

EXEC CICS DOCUMENT INSERT
          DOCTOKEN(ATOKEN)
          TEXT('Text to be replaced. ')
          LENGTH(21)

EXEC CICS DOCUMENT INSERT
          DOCTOKEN(ATOKEN)
          BOOKMARK('BMark2          ')

EXEC CICS DOCUMENT INSERT
          DOCTOKEN(ATOKEN)
          TEXT('Final sample text. ')
          LENGTH(19)

At this point the logical structure of the document will be as follows:

  Initial sample text. <BMark1>Text to be replaced. <BMark2>Final
  sample text.

You can now issue the command to replace the text between the two bookmarks, BMark1 and BMark2:

EXEC CICS DOCUMENT INSERT
          DOCTOKEN(ATOKEN)
          TEXT('Replacement Text. ')
          LENGTH(18)
          AT('BMark1          ')
          TO('BMark2          ')

The document now has the following logical structure:

   Initial sample text. <BMark1>Replacement Text.  <BMark2>Final
   sample text.

Code page conversion for documents

The documents that an application creates may be transmitted to systems running on other platforms; for example, when a document is used to supply a Web page to a client. Textual data that is in the code pages used by the CICS system must be converted to the code pages used on the target system. This process is known as code page conversion. A code page used by the CICS system is usually described as a host code page, except when CICS is acting as an HTTP client. A code page used by the target system is described as a client code page, or where the target system is a Web client or server using ASCII, it can be referred to as a character set.

You can make CICS documents include information about the code pages in which they have been created. When you create a document using the EXEC CICS DOCUMENT CREATE and EXEC CICS DOCUMENT INSERT commands, you can use the HOSTCODEPAGE option together with any of the TEXT, FROM, TEMPLATE and SYMBOL options, to indicate the code page for that block of data. Each block can be specified in a different code page.

When you use the EXEC CICS DOCUMENT RETRIEVE command to retrieve a document for sending, you can specify the CLNTCODEPAGE option to make the Document Handler to convert all the individual blocks from their respective host code pages, into a single client code page that is suitable for use by the target system.

Start of changeFor CICS Web support, when a CICS document is specified for sending by a Web-aware application program using the EXEC CICS WEB API commands, the EXEC CICS DOCUMENT RETRIEVE command is not used by the application program. Instead, the document token of the CICS document is specified, and CICS manages retrieval of the document. Conversion to a client code page is handled by CICS, according to options that the application program specifies on the EXEC CICS WEB API commands.End of change

Start of changeAlso for CICS Web support, when a CICS document template is specified in a URIMAP definition to provide a static response to a Web client, conversion to a client code page is handled by CICS. The host code page in which the template exists, and the client code page to which it should be converted, are specified in the URIMAP definition. When the static response is required, CICS creates a document using the template, retrieves the document, and carries out appropriate code page conversion.End of change

Start of changeCICS documents and document templates cannot be converted to or from the UTF-8 and UTF-16 character encodings. This restriction applies whether they are used as a static response in CICS Web support, retrieved by CICS in response to EXEC CICS WEB API commands, or retrieved by an application program using an EXEC CICS DOCUMENT RETRIEVE command.End of change

[[ Contents Previous Page | Next Page Index ]]