Setting up document templates

Document templates are portions of a document which can be created off-line, or in another CICS® program, and inserted into the document in the application program. Document templates are CICS resources, which you define using DOCTEMPLATE definitions; the name of the template is specified in the TEMPLATENAME attribute.

Templates can contain static data, and symbols whose values are inserted into the template when you issue the DOCUMENT CREATE or DOCUMENT INSERT command. The values to be subsituted are specified in the application program; they are associated with a particular document and cannot be used in a different document.

Templates can be retrieved from several different sources, to suit the way they are used in the application program; the DOCTEMPLATE definition specifies the source of the template:

If you attempt to use a template for which there is no installed DOCTEMPLATE definition, CICS attempts to retrieve the template from the partitioned data set with a DDNAME of DFHHTML.

Templates in a partitioned data set

Consider storing your templates in a partitioned data set when any of the following apply:

CICS loads a copy of the template from the partitioned data set when you install the corresponding DOCTEMPLATE definition. Therefore you can modify the template in the partitioned data set while CICS is running, and reinstall the definition in order to activate the changes.

A partitioned data set used to store templates may have one of the following record formats:

Records may contain sequence numbers in the following cases:

In other cases, there must be no sequence numbers in the records. If you use sequence numbers, they must be present in all the records; do not used partially sequenced members.

Templates in a CICS program

Consider coding a CICS program to contain a template when:

To code a program which contains a template:

  1. Code an Assembler CSECT containing
    1. An ENTRY statement, which denotes the start of the template
    2. Character constants (DC statements) defining the text that you wish to include in your template.
    3. An END statement
    For example:
             ENTRY WKLYHDR                             
    WKLYHDR  CSECT                                     
             DC    CL4'<HR>'                           
             DC    CL29'<H2>Weekly Status Report</H2>' 
             END                                       
  2. Assemble and link edit the program into your CICS application program library. Note that the name you give to the program can be different from the name of the entry point.
  3. Create and install a DOCTEMPLATE definition which specifies the name of the program in the Program attribute.

CICS will autoinstall the program on first reference, or you can create and install a PROGRAM definition.

Templates in CICS files, z/OS UNIX System Services HFS files, temporary storage, or transient data

Consider using one of these resources when you want to use dynamic data from an application program in a template. Which resource you use will depend upon:

In general, when a template is inserted into a document, all the data contained in the resource is used:

Temporary storage
The queue is read, in sequence, by ITEM number, and therefore all records in the queue are read, regardless of which records have been read by other applications.
Transient data
Because transient data uses a destructive read, when you insert data from a transient data queue into a template, the contents of the queue are no longer available to other applications.
CICS file
Start of changez/OS UNIX System Services HFS fileEnd of change
Start of change End of change

Creating templates in exit programs

Consider using an exit program for a template when:

When an application program requests a template which is defined as being created in an exit program, CICS calls the specified program, and passes a communication area; the communication area is mapped by the following copybooks:

The communication area contains the following fields:

dhtx_template_name_ptr
Contains a pointer to the name (up to 48 characters) of the template that is being requested.
dhtx_buffer_ptr
Contains the pointer of the CICS-supplied buffer in which the exit program returns the template.
dhtx_buffer_len
(Fullword binary.) Contains the length of the CICS-supplied buffer in which the exit program returns the template.
dhtx_message_len
(Fullword binary.) Use this field to return the length of a message that is issued when the exit program is unable to return a template. If there is no message, return a value of zero.
dhtx_message_ptr
Use this field to return the pointer of a message that explains why the exit program was unsuccessful. CICS writes this message to the CSDH transient data destination. If there is no message, return a value of zero.
dhtx_template_len
(Fullword binary.) Use this field to return the actual length of the template.
dhtx_append_crlf
Use the characters ‘1’ (append) or ‘0’ (do not append) to specify whether or not to add carriage return and line feed characters to the end of each line.
dhtx_return_code
(Fullword binary.) Use this field to indicate whether the exit program has successfully returned a template:

If the template to be returned is longer than dhtx_buffer_len, the template must be truncated to length dhtx_buffer_len and the exit program must set the length required in dhtx_template_len. The exit program is then called again with a larger buffer.

If your exit program sets a return code of 8, you can return an explanatory message, which is written to the CSDH transient data destination. Return the address and length of the message in dhtx_message_ptr and dhtx_message_len respectively. The storage which contains the message must be accessible to the caller of the exit program. For example, your exit program can issue a GETMAIN command to acquire storage for the message. CICS will release the storage when the task ends, unless you specify the SHARED option on the command.

[[ Contents Previous Page | Next Page Index ]]