Add Triggered Cache Manager Trigger Handler Description (QzhtAddTCMTriggerHandlerDesc) API

Important: Information for this topic supports the latest PTF levels for HTTP Server for i5/OS . It is recommended that you install the latest PTFs to upgrade to the latest level of the HTTP Server for i5/OS. Some of the topics documented here are not available prior to this update. See http://www.ibm.com/servers/eserver/iseries/software/http/services/service.htm Link outside Information Center for more information.
Required Parameter Group:
1 request variable Input Char(*)
2 length of request variable Input Binary(4)
3 request variable format Input Char(8)
4 error code I/O Char(*)
Library Name/Service Program: QTCM/QZHTINCONF
Threadsafe: Yes

Use the QzhtAddTCMTriggerHandlerDesc API to add new trigger handler descriptions to the configurations of triggered cache manager servers. New trigger handler descriptions are utilized by the triggered cache manager servers after they are restarted. The API is a callable service implemented as an ILE entry point within the QZHTINCONF *SRVPGM in the QTCM *LIB.

The QTCM/H(QZHTINCONF) header file includes ILE C prototypes for this API.

Authorities and locks

Required parameter group

request variable
INPUT: CHAR(*)

The variable used to pass the information used to add a new trigger handler description.

length of request variable
INPUT: BINARY(4)

The number of bytes that the calling program provides for Request variable.

request variable format
INPUT: CHAR(8)

The format name of the Request variable data. The following values must be used:

  • THDP0100: Basic information format for a trigger handler description.
  • THDP0200: Detailed information format for an *UPDATE type trigger handler description.
  • THDP0300: Detailed information format for a *PUBLISH type trigger handler description.
error code
I/O: CHAR(*)

The structure in which to return error information.

THDP0100 format

Note: When using this format, trigger handler description are added using default values for all unspecified values (according to the type specified by Trigger handler type). See other trigger handler description formats for details regarding these default values.
Offset Type Field
Dec Hex
0 0 Char(32) Server name
32 20 Char(32) Trigger handler description name
64 40 Char(10) Trigger handler type
74 4A Char(2) Reserved
76 4C Char(32) Data source
108 6C Binary(4) Offset to cache targets
112 70 Binary(4) Length of cache targets
116 74 Binary(4) Offset to ack targets
120 78 Binary(4) Length of ack targets
124 7C Binary(4) Offset to nack targets
128 80 Binary(4) Length of nack targets
132 84 Binary(4) Number of threads
    Char(*) Cache targets
    Char(*) Ack targets
    Char(*) Nack targets

THDP0100 format field descriptions

Ack targets
A list of acknowledgment target descriptions associated with the triggered cache manager server referenced by the new trigger handler description and used later, at server startup, to obtain information as to where successful process completion messages are sent. Descriptions must be listed by name, where each name is separated by one or more spaces, and padded with blanks if necessary. The default setting is to reference the descriptions currently designated as default acknowledgment target descriptions for the triggered cache manager server. If there are no descriptions currently designated as default, a null list is used. A null list indicates successful process completion messages are not sent.
Note: If a null list is specified, Offset to ack targets must equal 0 (QZHT_NONE), or -1 (QZHT_DEFAULT). See Offset to ack targets for more details. Messages concerning successful process completion of triggers referencing this handler are sent to all listed acknowledgment targets. An escape message is sent if any referenced description does not currently exist.
Cache targets
A list of cache target descriptions associated with the triggered cache manager server referenced by the new trigger handler description and used later, at server startup, to obtain information about the cache targets to which the trigger handler sends data. Descriptions must be listed by name, where each name is separated by one or more spaces, and padded with blanks if necessary. The default setting is to reference the descriptions currently designated as default cache target descriptions for the triggered cache manager server. If there are no descriptions currently designated as default, a null list is used. A null list indicates data is not sent to cache targets.
Note: If a null list is specified, Offset to ack targets must equal 0 (QZHT_NONE), or -1 (QZHT_DEFAULT). See Offset to ack targets for more details. Data processed by this trigger handler is sent to all listed cache targets. An escape message is sent if any referenced description does not currently exist.
Data source
The name of a data source description associated with the triggered cache manager server referenced by the new trigger handler description and used later, at server startup, to obtain information about the data source from which the trigger handler receives data. The value must be a data source description name, or one of the special values described below (left justified and padded with blanks if necessary). The default setting references the description currently designated as the default data source description for the triggered cache manager server.

Special values and their meanings are as follows:

*DEFAULT
QZHT_DEFAULT_CHAR: The default value is referenced.
Note: An escape message is sent if the referenced description does not currently exist, or if *DEFAULT is specified and there is currently no default data source description for the server.
Length of ack targets
The length of the information for the Ack targets entry.
Note: If Offset to ack targets equals 0 (QZHT_NONE), or -1 (QZHT_DEFAULT), this value must equal 0.
Length of cache targets
The length of the information for the Cache targets entry.
Note: If Offset to cache targets equals 0 (QZHT_NONE), or -1 (QZHT_DEFAULT), this value must equal 0.
Length of nack targets
The length of the information for the Nack targets entry.
Note: If Offset to nack targets equals 0 (QZHT_NONE), or -1 (QZHT_DEFAULT), this value must equal 0.
Nack targets
A list of acknowledgment target descriptions associated with the triggered cache manager server referenced by the new trigger handler description and used later, at server startup, to obtain information as to where failed process completion messages are sent. Descriptions must be listed by name, where each name is separated by one or more spaces, and padded with blanks if necessary. The default setting is to reference the descriptions currently designated as default acknowledgment target descriptions for the triggered cache manager server. If there are no descriptions currently designated as default, a null list is used. A null list indicates failed process completion messages are not sent.
Note: If a null list is specified, Offset to nack targets must equal 0 (QZHT_NONE), or -1 (QZHT_DEFAULT). See Offset to nack targets for more details. Messages concerning failed trigger process completion referencing this handler are sent to all listed acknowledgment targets. An escape message is sent if any referenced description does not currently exist.
Number of threads
The number of concurrent threads the triggered cache manager server spawns when processing triggers sent to this trigger handler. The value must be greater that 0 and less than 231 (or 2.147x109), or equal to one of the special values described below. The default value is 10.

Special values and their meanings are as follows:

-1 QZHT_DEFAULT: The default value is used.
Offset to ack targets
The offset from the beginning of the request variable to the Ack targets data, in bytes. The value must be greater than 0, or equal to one of the special values described below.

Special values and their meanings are as follows:

0 QZHT_NONE: A null list is specified for Ack targets indicating successful process completion messages are not sent.
-1 QZHT_DEFAULT: The default descriptions, if any, are referenced for Ack targets.
Offset to cache targets
The offset from the beginning of the request variable to the Cache targets data, in bytes. The value must be greater than 0, or equal to one of the special values described below.

Special values and their meanings are as follows:

0 QZHT_NONE: A null list is specified for Cache targets indicating data is not sent to cache targets.
-1 QZHT_DEFAULT: The default descriptions, if any, are referenced for Cache targets.
Offset to nack targets
The offset from the beginning of the request variable to the Nack targets data, in bytes. The value must be greater than 0, or equal to one of the special values described below.

Special values and their meanings are as follows:

0 QZHT_NONE: A null list is specified for Nack targets indicating failed process completion messages are not sent.
-1 QZHT_DEFAULT: The default descriptions, if any, are referenced for Nack targets.
Server name
The name used to identify the triggered cache manager server for which the new description is associated (left justified and padded with blanks if necessary).
Trigger handler description name
The name used by the new trigger handler description (left justified and padded with blanks if necessary).
Note: Trigger handler description names must be unique for each triggered cache manager server.
Trigger handler type
The trigger handler type (left justified and padded with blanks if necessary). The value must be one of the special values described below.

Special values and their meanings are as follows:

*UPDATE
QZHT_UPDATE_TYPE: A *UPDATE type is described.
*PUBLISH
QZHT_PUBLISH_TYPE: A *PUBLISH type is described.

THDP0200 format

Offset Type Field
Dec Hex
0 0   Everything from THDP0100 format
136 88 Binary(4) Cache request queue priority
140 8C Binary(4) Trigger queue collapse policy

THDP0200 format field description

Cache request queue priority
Specifies the trigger handler priority value when submitting requests to the cache targets. Lower values indicate higher priority. The value must be greater that 0 and less than 231 (or 2.147x109), or equal to one of the special values described below. The default value is 231 (the lowest priority).

Special values and their meanings are as follows:

-1 QZHT_DEFAULT: The default value is used.
Note: Triggered cache manager servers queue the trigger handler requests to the cache targets and process them according to queue priority. Requests from trigger handlers with higher priority are processed before requests from trigger handlers with lower priority. The trigger handler queue priority can be changed while servers are active by using the -chspriority command in a trigger message.
Trigger queue collapse policy
Specifies if identical triggers waiting on the request queue, for this trigger handler, are collapsed. The value must equal one of the special values described below. The default value is 1 (QZHT_YES).

Special values and their meanings are as follows:

1 QZHT_YES, QZHT_TRUE, QZHT_ENABLED: Identical triggers are collapsed.
0 QZHT_NO, QZHT_FALSE, QZHT_DISABLED: Identical triggers are not collapsed.
-1 QZHT_DEFAULT: The default value is used.
Note: Only triggers using the -objects keyword can be collapsed. Identical triggers are those having an identical set of listed objects. The order of the listed objects is not important. Once a trigger handler begins processing a trigger, it is not collapsed.

THDP0300 format

Offset Type Field
Dec Hex
0 0   Everything from THDP0100 format
136 88 Char(32) Object dependency graph
168 A8 Char(32) Rule set
200 C8 Binary(4) Offset to traversal edge name
204 CC Binary(4) Length of traversal edge name
208 D0 Binary(4) Offset to default included file
212 D4 Binary(4) Length of default included file
216 D8 Binary(4) Include dependency information
220 DC Binary(4) Include triggered file information
224 E0 Binary(4) Include cached file information
    Char(*) Traversal edge type
    Char(*) Default include file

THDP0300 format field description

Default included file
The name of a file the trigger handler includes, by global default, as a replacement for included files that have not been triggered (when a local default file is not specified or available). The file name must be left justified and padded with blanks if necessary. The default value is null, indicating that a global default file name is not specified for this trigger handler description.
Note: If the value is null, Offset to default included file must equal 0 (QZHT_NONE), or -1 (QZHT_DEFAULT). See Offset to default included file for more details. The file specified as a global default must be triggered (at runtime) before it can be used.
Include cached file information
Specifies if a list of names for all files sent to cache targets, as a result of handling original trigger requests, is included in successful process completion messages. The value must equal one of the special values described below. The default value is 0 (QZHT_NO).

Special values and their meanings are as follows:

1 QZHT_YES, QZHT_TRUE, QZHT_ENABLED: A list of names is included.
0 QZHT_NO, QZHT_FALSE, QZHT_DISABLED: A list of names is not included.
-1 QZHT_DEFAULT: The default value is used.
Include dependency information
Specifies if information concerning all dependent files, assembled into triggered files as a result of handling original trigger request, is included in successful process completion messages. The value must equal one of the special values described below. The default value is 0 (QZHT_NO).

Special values and their meanings are as follows:

1 QZHT_YES, QZHT_TRUE, QZHT_ENABLED: Information is included.
0 QZHT_NO, QZHT_FALSE, QZHT_DISABLED: Information is not included.
-1 QZHT_DEFAULT: The default value is used.
Include triggered file information
Specifies if a list of names for all files triggered, as a result of handling original trigger requests, is included in successful process completion messages. The value must equal one of the special values described below. The default value is 0 (QZHT_NO).

Special values and their meanings are as follows:

1 QZHT_YES, QZHT_TRUE, QZHT_ENABLED: A list of names is included.
0 QZHT_NO, QZHT_FALSE, QZHT_DISABLED: A list of names is not included.
-1 QZHT_DEFAULT: The default value is used.
Length of default included file
The length of information for the Default included file entry.
Note: If Offset to traversal edge type equals 0 (QZHT_NONE), or -1 (QZHT_DEFAULT), this value must equal 0.
Object dependency graph
The name of an object dependency graph description associated with the triggered cache manager server referenced by the new trigger handler description and used later, at server startup, to identify which object dependency graph is used by the handler to record and obtain object dependency information. The value must be an object dependency graph description name, or one of the special values described below (left justified and padded with blanks if necessary). The default setting is to reference the description currently designated as the default object dependency graph description for the triggered cache manager server.

Special values and their meanings are as follows:

*DEFAULT
QZHT_DEFAULT_CHAR: The default is referenced.
Note: An object dependency graph description is required. An escape message is sent if the referenced description does not currently exist, or if *DEFAULT is specified and there is currently no default object dependency graph description for the server.
Offset to default included file
The offset from the beginning of the request variable to the Default included file data, in bytes. The value must be greater than 0, or equal to one of the special values described below.

Special values and their meanings are as follows:

0 QZHT_NONE: Same as -1 (QZHT_DEFAULT).
-1 QZHT_DEFAULT: The default value for Default included file is used.
Offset to traversal edge type
The offset from the beginning of the request variable to the Traversal edge type data, in bytes. The value must be greater than 0, or equal to one of the special values described below.

Special values and their meanings are as follows:

0 QZHT_NONE: Same as -1 (QZHT_DEFAULT).
-1 QZHT_DEFAULT: The default value for Traversal edge type is used.
Rule set
The name of a rule set associated with the triggered cache manager server referenced by the new trigger handler description and used later, at server startup, to identify which publishing rules are used by the handler. The value must be a rule set name, or one of the special values described below (left justified and padded with blanks if necessary).

Special values and their meanings are as follows:

*DEFAULT
QZHT_DEFAULT_CHAR: The default rule set currently associated with the triggered cache manager server is referenced.
*NONE
QZHT_NONE_CHAR: No rule set is referenced by the trigger handler.
Note: Triggers that specify files that do not match any publishing rules, in the specified rule set, are processed according to the default publishing rule. That is, they are read from the data source and sent to all cache targets (they are not parsed). An empty rule set has the same affect as not specifying a rule set at all. An escape message is sent if the referenced description does not currently exist, or if *DEFAULT is specified and there is currently no default Rule Set for the server.
Traversal edge type
The name of an object dependency graph (ODG) edge type used by the trigger handler to determine object dependencies when assembling files. The edge type name must be left justified and padded with blanks if necessary. The default name is composition.
Note: If the value is null, Offset to traversal edge type must equal 0 (QZHT_NONE), or -1 (QZHT_DEFAULT). Only edges of the specified type are traversed by this trigger handler to determine object dependencies.

Error messages

TCM7001 E
User &1 is not authorized.
TCM7030 E
Severe error occurred while addressing parameter list.
TCM7031 E
Request variable format is not valid.
TCM7033 E
Length of request variable is not valid for the specified format.
TCM703E E
Error code parameter is not valid
TCM70F0 E
Unknown error occurred while processing request.
TCM7101 E
User QTCM is not authorized to the configuration file for triggered cache manager server &1.
TCM7190 E
A configuration file for triggered cache manager server &1 was not found.
TCM7222 E
A default &1 is not designated for triggered cache manager server &2.
TCM7293 E
A &1 using the name &2 already exists for triggered cache manager server &3.
TCM72C0 E
Triggered cache manager &1 name is not valid.
TCM72C1 E
Triggered cache manager &1 type is not valid.
TCM72C2 E
Triggered cache manager description type &1 cannot be specified when using data format &2.
TCM72C3 E
Value passed to offset &1 is not valid.
TCM74C0 E
Triggered cache manager server name is not valid.