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:
- from a partitioned data set
- from a CICS program
- from a CICS file
from a z/OS® UNIX System Services HFS file
- from a temporary storage queue
- from a transient data queue
- from an exit program
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.
Consider storing your templates in a partitioned data set when any of the
following apply:
- You want to edit your template on-line, or import the template from an
HTML editor.
- You want to use templates that have been created from BMS maps
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:
- FB (fixed length blocked)
- VB (variable length blocked)
- U (unblocked)
Records may contain sequence numbers in the following cases:
- When the record format is FB, and the record length is 80; the sequence
numbers must be in positions 73 through 80.
- When the record format is VB; the sequence numbers must be in positions
1 through 8.
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.
Consider coding a CICS program to contain a template when:
- You need to minimize the overhead of retrieving the template
- The template is static; in other words, the contents of the template do
not change dynamically
- The same template is used by a several applications
To code a program which contains a template:
- Code an Assembler CSECT containing
- An ENTRY statement, which denotes the start of the template
- Character constants (DC statements) defining the text that you wish to
include in your template.
- An END statement
For example:
ENTRY WKLYHDR
WKLYHDR CSECT
DC CL4'<HR>'
DC CL29'<H2>Weekly Status Report</H2>'
END
- 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.
- 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.
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:
- how the application program stores its data
- whether the existing data can be used directly in the template, or needs
to be modified
- whether the data must be preserved after it is used in the template
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
-
- Entry-sequenced data sets (ESDS) are read in sequence of relative byte
address.
- Relative record data sets (RRDS) are read in sequence of relative record
number.
- Other data sets are read in sequence of key field.
z/OS UNIX System Services HFS file
- All the data in the file is used.
- In the DOCTEMPLATE definition, you need to provide the fully-qualified
name of the HFS file, which can be up to 255 characters in length.
- The CICS region must have permissions to access z/OS UNIX, and it must
have permission to access the HFS directory containing the file, and the file
itself. Java™ Applications in CICS explains how to achieve this.
Consider using an exit program for a template when:
- You need to minimize the overhead of retrieving the template
- The contents of the template change dynamically
- The same template is used by a several applications
- You want to retrieve the contents of the template from a non-CICS resource
(for example, DB2®)
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:
- DFHDHTXD (Assembler)
- DFHDHTXH (C)
- DFHDHTXL (PL/I)
- DFHDHTXO (COBOL)
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:
- A return code of 0 indicates that the exit has returned a template.
- A return code of 8 indicates that the exit has not returned a template.
In this case, CICS raises a TEMPLATERR condition in the application program.
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 ]]