Add Triggered Cache Manager Acknowledgment Target Description (QzhtAddTCMAckTargetDesc) 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 or 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 QzhtAddTCMAckTargetDesc API to add new acknowledgment target descriptions to the configurations of triggered cache manager servers. New acknowledgment target descriptions are referenced subsequently, by name, from trigger handler descriptions associated with the same server. New acknowledgment target descriptions are utilized by all trigger handler descriptions, referencing then the next time the servers 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

*IOSYSCFG special authority

Required parameter group

request variable: INPUT: CHAR(*)
The variable used to pass the information used to add a new acknowledgment target description. See Acknowledgment target description formats for more information.

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:

ATDP0100: Basic information format for an acknowledgment target description.
ATDP0200: Detailed information format for an *HTTP1 type acknowledgment target description.
ATDP0210: Detailed information format for an *HTTP2 type acknowledgment target description.

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

ATDP0100 format

Offset		Type	Field
Dec	Hex	Type	Field
0	0	Char(32)	Server name
32	20	Char(32)	Acknowledgement target description name
64	40	Char(10)	Acknowledgement target type
74	4A	Char(2)	Reserved
76	4C	Binary(4)	Default property
80	50	Binary(4)	Number of threads
84	54	Binary(4)	Initial state

ATDP0100 format field descriptions

Note: Acknowledgment target descriptions are added using default values for all unspecified values according to the type specified by Acknowledgment target type). See other acknowledgment target description formats for details regarding these default values.

Acknowledgement target description name: The name used by the new acknowledgment target description (left justified and padded with blanks if necessary).
Note: Acknowledgment target description names must be unique for each triggered cache manager server. They are referenced, by name, from trigger handler descriptions associated with the same server.

Acknowledgement target type

The type of acknowledgment target description that is added (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:

*HTTP1: QZHT_HTTP_TYPE1: An *HTTP1 type is added.

*HTTP2: QZHT_HTTP_TYPE2: An *HTTP2 type is added.

Default property

Specifies if the new description is the default acknowledgment target description for the triggered cache manager server specified in Server name. 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: The description is the default cache target description for this server.
0	QZHT_NO, QZHT_FALSE, QZHT_DISABLED: The description is not the default cache target description.
-1	QZHT_DEFAULT: The default value is used.

Note: Multiple default acknowledgment target descriptions are allowed. Trigger handler descriptions, added or changed using the *DEFAULT special value, reference all acknowledgment target descriptions designated as default at the time the trigger handler descriptions are added or changed.

Initial state

Specifies the state that the triggered cache manager server request processor, for this acknowledgment target, is in at server startup. The value must equal one of the special values described below. The default value is 1 (QZHT_ENABLED).

1	QZHT_YES, QZHT_TRUE, QZHT_ENABLED: The request processor is enabled at server startup.
0	QZHT_NO, QZHT_FALSE, QZHT_DISABLED: The request processor is disabled at server startup.
-1	QZHT_DEFAULT: The default value is used.

Note: The state of a acknowledgment target request processor can be changed while the triggered cache manager server is active by using the -chack command in a trigger message.

Number of threads

The number of concurrent threads the triggered cache manager server spawns when processing requests sent to this acknowledgment target. The value must be greater that 0 and less than 2³¹ (or 2.147x10⁹), or equal to one of the special values described below. The default value is 5.

Special values and their meanings are as follows:

-1	QZHT_DEFAULT: The default value is used.

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

ATDP0200 format

Offset		Type	Field
Dec	Hex	Type	Field
0	0	Char(256)	Everything from ATDP0100 format
88	58	Binary(4)	HTTP IP interface
344	158	Binary(4)	HTTP TCP port
348	15C	Binary(4)	Offset to HTTP URI root
352	160	Binary(4)	Length of HTTP URI root
356	164	Binary(4)	HTTP keepalive
360	168	Binary(4)	Timeout
		Char(*)	HTTP URI root

ATDP0200 format field descriptions

HTTP IP interface

The IP host name or address of the system hosting an HTTP server that accepts completion messages (left justified and padded with blanks if necessary). The value must be a host name (for example, server.mycompany.com), dotted address (for example, 192.168.3.57), or one of the special values described below. If a host name is specified, it must use proper naming conventions as defined by RFC 1034, Domain Names - Concepts and Facilities. If a dotted address is specified, it must use proper IP version 4 address conventions as defined by RFC 791, Internet Protocol. The default value is 127.0.0.1, the local system loopback interface.

Special values and their meanings are as follows:

*DEFAULT: QZHT_DEFAULT_CHAR: The default value is used.

HTTP keepalive

Specifies if connections to HTTP Server are kept open for reuse after data is transferred. The value must equal one of the special values described below. The default value is 0 (QZHT_DISABLED).

Special values and their meanings are as follows:

1	QZHT_YES, QZHT_TRUE, QZHT_ENABLED: The connection is kept open after data transfer.
0	QZHT_NO, QZHT_FALSE, QZHT_DISABLED: The connection is closed after data transfer.
-1	QZHT_DEFAULT: The default value is used.

Note: HTTP Server must support keepalive for this option to work properly.

HTTP TCP port

The TCP port number upon which HTTP Server listens for incoming requests. The value must be greater than 0 and less than 65536, or equal to one of the special values described below. The default value is 80.

Special values and their meanings are as follows:

-1	QZHT_DEFAULT: The default value is used.

Note: The TCP port number is used in combination with the IP host name or address in HTTP IP interface to establish communication with HTTP Server acknowledgment target.

HTTP URI root: The path of HTTP Server URI that is the root of this acknowledgment target (left justified and padded with blanks if necessary). The value must be a path acceptable to HTTP Server. The default path is / .
Note: All completion message requests sent to the acknowledgment target are prepended with this path. If the value is null, Offset to HTTP URI root must equal 0 (QZHT_NONE), or -1 (QZHT_DEFAULT). See Offset to HTTP URI root for more details.

Length of HTTP URI root: The length of the information for the HTTP URI root entry.
Note: If Offset to HTTP URI root equals 0 (QZHT_NONE), or -1 (QZHT_DEFAULT), this value must equal 0.

Offset to HTTP URI root

The offset from the beginning of the request variable to the HTTP URI root data, in bytes. The value must be greater than 0, or equal to one of the special values defined below.

Special values and their meanings are as follows:

0	QZHT_NONE: Same as -1 (QZHT_DEFAULT).
-1	QZHT_DEFAULT: The default value is used for HTTP URI root.

Timeout

The number of seconds the triggered cache manager server waits before canceling a read operation on sockets and ending transactions, with the HTTP host, in error. The value must be greater than 0 and less than 2³¹ (or 2.147x10⁹), or equal to one of the special values described below. The default value is 0 (QZHT_DISABLED).

Special values and their meanings are as follows:

0	QZHT_NO, QZHT_FALSE, QZHT_DISABLED: The time out operation is disabled. The triggered cache manager server should never cancel a read operation.
-1	QZHT_DEFAULT: The default value is used.

ATDP0210 format

Offset		Type	Field
Dec	Hex	Type	Field
0	0		Everything from ATDP0100 format
88	58	Char(32)	HTTP host
120	78	Binary(4)	HTTP TCP port
124	7C	Binary(4)	Offset to HTTP URI root
128	80	Binary(4)	Length of HTTP URI root
132	84	Binary(4)	HTTP keepalive
136	88	Binary(4)	Timeout
		Char(*)	HTTP URI root

ATDP0210 format field descriptions

HTTP host

The name of a host description associated with the triggered cache manager server that is referenced by the new acknowledgment target description and used later, at server startup, to obtain information about the system hosting an HTTP server accepting completion messages. The value must be a host description name, or one of the special values described below (left justified and padded with blanks if necessary). The default value is to reference the description currently designated as the default host 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: See HTTP TCP port for more information. An escape message is sent if the referenced description does not currently exist, or if *DEFAULT is specified and there is currently no default host description for the server.

HTTP keepalive

Specifies if connections to HTTP Server are kept open for reuse after completion messages are sent. The value must equal one of the special values described below. The default value is 0 (QZHT_DISABLED).

Special values and their meanings are as follows:

1	QZHT_YES, QZHT_TRUE, QZHT_ENABLED: The connection is kept open after messages are sent.
0	QZHT_NO, QZHT_FALSE, QZHT_DISABLED: The connection is closed after messages are sent.
-1	QZHT_DEFAULT: The default value is used.

Note: HTTP Server must support keepalive for this option to work properly.

HTTP TCP port

The TCP port number upon which HTTP Server listens for incoming completion messages. The value must be greater than 0 and less than 65536, or equal to one of the special values described below. The default value is 80.

Special values and their meanings are as follows:

-1	QZHT_DEFAULT: The default value is used.

Note: The TCP port number is used in combination with information obtained at server startup from the host description specified in HTTP host to establish communication with HTTP Server acknowledgment target.

HTTP URI root: The path of HTTP Server URI that is the root of this acknowledgment target (left justified and padded with blanks if necessary). The value must be a path acceptable to HTTP Server. The default path is / .
Note: All requests to send completion messages to this acknowledgment target are prepended with this path. If the value is null, Offset to HTTP URI root must equal 0 (QZHT_NONE), or -1 (QZHT_DEFAULT). See Offset to HTTP URI root for more details.

Length of HTTP URI root: The length of the information for the HTTP URI root entry.
Note: If Offset to HTTP URI root equals 0 (QZHT_NONE), or -1 (QZHT_DEFAULT), this value must equal 0.

Offset to HTTP URI root

The offset from the beginning of the request variable to the HTTP URI root data, in bytes. The value must be greater than 0, or equal to one of the special values defined below.

Special values and their meanings are as follows:

0	QZHT_NONE: Same as -1 (QZHT_DEFAULT).
-1	QZHT_DEFAULT: The default path is used for HTTP URI root.

Timeout

Special values and their meanings are as follows:

0	QZHT_NO, QZHT_FALSE, QZHT_DISABLED: The time out operation is disabled. The triggered cache manager server should never cancel a read operation.
-1	QZHT_DEFAULT: The default value is used.

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.