Templates in CICS programs

A document template in a program has the least overhead for retrieving the template, although for other formats, caching also minimizes the overhead after the first request. Programs are an appropriate format to choose if the same template is used by several applications. A CICS program is most suitable where the template is not changed frequently, because a program cannot be easily edited and must be recompiled.

About this task

Document templates contained in CICS® programs have the attribute PROGRAM in their DOCTEMPLATE resource definitions.

Templates contained in CICS programs are never cached by the CICS document handler. Programs are already cached by the CICS loader.

For this type of document template, you can use the SET DOCTEMPLATE NEWCOPY command to phase in a new copy of the program. The command is equivalent to SET PROGRAM PHASEIN for the specified program. Subsequent requests to use the document template use the new copy, including later requests within the same task.

To code a program which contains a template:

Procedure

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 want to include in your template.
3. An END statement.
4. Invocations for the DFHDHTL macro, to generate a prolog and epilog for the document template.
  DFHDHTL - program template prolog and epilog macro documents this macro.
For example:
```
DOCTPROG CSECT                                    
DOCTPROG AMODE 31                                 
DOCTPROG RMODE ANY                                
         DFHDHTL TYPE=INITIAL,ENTRY=WKLYHDR       
         DC    CL4'<HR>'                          
         DC    CL29'<H2>Weekly Status Report</H2>'
         DFHDHTL TYPE=FINAL                       
         END   WKLYHDR
```
The DFHDHTL macro is used because the template program must be an exact multiple of eight bytes. If this is not the case, the binder might insert spurious binary characters at the end of the template, which can produce unpredictable output when the template is used in a document. The DFHDHTL macro creates the necessary padding.
Assemble and link edit the program into your CICS application program library.
The name you give to the program can be different from the name of the entry point.
Create and install a DOCTEMPLATE resource definition which specifies the name of the program in the PROGRAM attribute.

What to do next

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