Communication area for templates in exit programs

The communication area for an exit program which supplies a document template is mapped by a CICS-supplied copybook.

The supplied copybooks are:
  • 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.
dhtx_cache_response
Use the characters '1' (cache) or '0' (do not cache) to specify whether or not the output from the exit program should be cached by the CICS document handler. The value of dhtx_cache_response is initialized to '0', so the default action is not to cache the response of the exit program, unless the exit changes this value.

When a document template is cached, subsequent requests receive the cached copy. The exit program is not called again as long as the cached copy is available, until the EXEC CICS SET DOCTEMPLATE NEWCOPY command is issued to refresh the exit program and the cached copy. A refreshed exit program can specify a different value for dhtx_cache_response, and CICS honors the change.

Templates that change dynamically should not be cached, but if the template does not change, caching is suitable as it improves the performance of requests.

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.