Retrieve Triggered Cache Manager Trigger Handler Description (QzhtRtvTCMTriggerHandlerDesc) 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	receiver variable	Output	Char(*)
2	length of receiver variable	Input	Binary(4)
3	receiver variable format	Input	Char(8)
4	server name	Input	Char(32)
5	description name	Input	Char(32)
6	error code	I/O	Char(*)
Library Name/Service Program: QTCM/QZHTINCONF
Threadsafe: Yes

Use the QzhtRtvTCMTriggerHandlerDesc API to retrieve information from trigger handlers associated with triggered cache manager servers. 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

*IOSYSCFG special authority

Required parameter group

receiver variable: OUTPUT: CHAR(*)
The variable used to return trigger handler description information.

length of receiver variable: INPUT: BINARY(4)
The number of bytes that the calling program provides for Receiver variable. This value must be greater than or equal to 8.

receiver variable format

INPUT: CHAR(8)

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

THDG0100: Basic information format for a trigger handler description.
THDG0200: Detailed information format for an *UPDATE type trigger handler description.
THDG0300: Detailed information format for a *PUBLISH type trigger handler description.

server name: INPUT: CHAR(32)
The name used to identify the server for which information is retrieved (left justified and padded with blanks if necessary).

description name: INPUT: CHAR(32)
The name used to identify which trigger handler description information is retrieved (left justified and padded with blanks if necessary).

error code: I/O: CHAR(*)
The structure in which to return error information.

THDG0100 format

When the trigger handler description type is unknown, use the THDG0100 format and the basic information (including trigger handler type) is returned.

Offset		Type	Field
Dec	Hex	Type	Field
0	0	Binary(4)	Bytes returned
4	4	Binary(4)	Bytes available
8	8	Char(32)	Server name
40	28	Char(32)	Trigger handler description name
72	48	Char(10)	Trigger handler type
82	52	Char(2)	Reserved
84	54	Char(32)	Data source
116	74	Binary(4)	offset to cache targets
120	78	Binary(4)	Length of cache targets
124	7C	Binary(4)	Offset to ack targets
128	80	Binary(4)	Length of ack targets
132	84	Binary(4)	Offset to nack targets
136	88	Binary(4)	Length of nack targets
140	8C	Binary(4)	Number of threads
		Char(*)	Cache targets
		Char(*)	Ack targets
		Char(*)	Nack targets

THDG0100 format field descriptions

Ack targets: A list of acknowledgment target descriptions referenced by the new trigger handler description and used, 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 (left justified and padded with blanks if necessary).
Note: If a null list is returned, Offset to ack targets must equal 0 (QZHT_NONE), indicating no acknowledgment target descriptions are currently referenced. Messages concerning successful process completion of triggers referencing this handler are sent to all listed acknowledgment targets.

Bytes available: The number of information bytes available for return to the caller of the API.
Note: If this value is greater than the value of Bytes returned, the receiver was not large enough to return all information.

Bytes returned: The number of information bytes returned to the caller of the API.

Cache targets: The list of cache target descriptions referenced by the trigger handler descriptions and used, at server startup, to obtain information about the cache targets to which the trigger handler sends data. Returned descriptions must be listed by name, where each name is separated by one or more spaces, left justified, and padded with blanks if necessary.
Note: If a null list is returned, Offset to cache targets must equal 0 (QZHT_NONE), indicating no cache target descriptions are currently referenced. Data processed by this trigger handler is sent to all listed cache targets.

Data source: The name of a data source description referenced by the new trigger handler description and used, at server startup, to obtain information about the data source from which the trigger handler retrieves data. The value must be a data source description name (left justified and padded with blanks if necessary).

Length of ack targets: The length of the information returned for the Ack targets entry.

Length of cache targets: The length of the information returned for the Cache targets entry.

Length of nack targets: The length of the information returned for the Nack targets entry.

Nack targets: The list of acknowledgment target descriptions referenced by the new trigger handler description and used, 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, left justified, and padded with blanks if necessary.
Note: If a null list is specified, Offset to nack targets must equal 0 (QZHT_NONE), indicating no acknowledgment target descriptions are currently referenced. Messages concerning failed trigger processes, referencing this handler, are sent to all listed acknowledgment targets.

Number of threads: The number of concurrent threads the triggered cache manager server spawns when processing triggers that are sent to this trigger handler. The value must be greater that 0 and less than 2³¹ (or 2.147x10⁹).

Offset to ack targets

The offset from the beginning of the receiver 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 no acknowledgment target descriptions are currently referenced.

Offset to cache targets

The offset from the beginning of the receiver 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 no cache target descriptions are currently referenced.

Offset to nack targets

The offset from the beginning of the receiver 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 no acknowledgment target descriptions are currently referenced.

Server name: The name used to identify the triggered cache manager server for which the description is associated (left justified and padded with blanks if necessary).

Trigger handler description name: The name of the trigger handler description (left justified and padded with blanks if necessary).

Trigger handler type

The trigger handler description 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

*PUBLISH: QZHT_PUBLISH_TYPE

THDG0200 format

Offset		Type	Field
Dec	Hex	Type	Field
0	0		Everything from THDP0100 format
144	90	Binary(4)	Cache request queue priority
148	94	Binary(4)	Trigger queue collapse policy

THDG0200 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 2³¹ (or 2.147x10⁹).
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.

Special values and their meanings are as follows:

1	QZHT_YES, QZHT_TRUE, QZHT_ENABLED: Identical triggers, waiting on the request queue for this trigger, are collapsed.
0	QZHT_NO, QZHT_FALSE, QZHT_DISABLED: Identical triggers are not collapsed.

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.

THDG0300 format

Offset		Type	Field
Dec	Hex
0	0		Everything from THDP0100 format
14	90	Char(32)	Object dependency graph
176	B0	Char(32)	Rule set
208	D0	Binary(4)	Offset to traversal edge name
212	D4	Binary(4)	Length of traversal edge name
216	D8	Binary(4)	Offset to default included file
220	DC	Binary(4)	Length of default included file
224	E0	Binary(4)	Include dependency information
228	E4	Binary(4)	Include triggered file information
22C	E8	Binary(4)	Include cached file information
		Char(*)	Traversal edge type
		Char(*)	Default included file

THDG0300 format field descriptions

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.
Note: If the value is null, Offset to default included file must equal 0 (QZHT_NONE), indicating that a global default file name is not specified for this trigger handler description. 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.

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.

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.

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.

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.

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.

Length of default included file: The length of information for the Default included file entry.

Length of traversal edge type: The length of the information returned for the Traversal edge type entry.

Object dependency graph: The name of an object dependency graph description referenced by the trigger handler description and used, 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 (left justified and padded with blanks if necessary).

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: The value is null for Default included file.

Offset to traversal edge type: The offset from the beginning of the request variable to the Traversal edge type data, in bytes.

Rule set

The name of a rule set referenced by the trigger handler description and used, 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:

*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.

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.
Note: Only edges of the specified type are traversed by this trigger handler to determine object dependencies.

Retrieve Triggered Cache Manager Trigger Handler Description (QzhtRtvTCMTriggerHandlerDesc) API

Authorities and locks

Required parameter group

THDG0100 format

THDG0100 format field descriptions

THDG0200 format

THDG0200 format field description

THDG0300 format

THDG0300 format field descriptions

Error messages