Retrieve Triggered Cache Manager Acknowledgment Target Description (QzhtRtvTCMAckTargetDesc) 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 QzhtRtvTCMAckTargetDesc API to retrieve information from acknowledgment target descriptions 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

Required parameter group

receiver variable
OUTPUT: CHAR(*)

The variable used to return acknowledgment target description information. See Acknowledgment target description formats for more 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:

  • ATDG0100: Basic information format for an acknowledgment target description.
  • ATDG0200: Detailed information format for an *HTTP1 type acknowledgment target description.
  • ATDG0210: Detailed information format for an *HTTP2 type acknowledgment target description.
server name
INPUT: CHAR(32)

The name used to identify the triggered cache manager server from which information is retrieved (left justified and padded with blanks if necessary).

description name
INPUT: CHAR(32)

The name used to identify the retrieved acknowledgment target description information (left justified and padded with blanks if necessary).

error code
I/O: CHAR(*)

The structure in which to return error information.

ATDG0100 format

Offset Type Field
Dec Hex
0 0 Binary(4) Bytes returned
4 4 Binary(4) Bytes available
8 8 Char(32) Server name
40 28 Char(32) Acknowledgement target description name
72 40 Char(10) Acknowledgement target type
82 52 Char(2) Reserved
84 56 Binary(4) Default property
88 58 Binary(4) Number of threads
92 5C Binary(4) Initial state

ATDG0100 format field descriptions

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 variable was not large enough to return all information.
Bytes returned
The number of information bytes returned to the caller of the API.
Acknowledgement target description name
The acknowledgment target description name (left justified and padded with blanks if necessary).
Acknowledgement target type
The acknowledgment target description type (left justified and padded with blanks if necessary). The value returned is one of the special values below.

Special values and their meanings are as follows:

*HTTP1
QZHT_HTTP_TYPE1
*HTTP2
QZHT_HTTP_TYPE2
Default property
Indicates if the description is a current default acknowledgment target description for the triggered cache manager server specified in Server name. The returned value equals one of the special values described below.

Special values and their meanings are as follows:

0 QZHT_NO, QZHT_FALSE, QZHT_DISABLED: The description is a current default acknowledgment target description for this server.
-1 QZHT_DEFAULT: The description is not a current default acknowledgment target description.
Note: Multiple default acknowledgment target descriptions are possible.
Initial state
Indicates if the triggered cache manager server message processor, for this acknowledgment target, is enabled or disabled at server startup. The returned value equals one of the special values described below.

Special values and their meanings are as follows:

0 QZHT_NO, QZHT_FALSE, QZHT_DISABLED: The message processor is enabled at server startup.
-1 QZHT_DEFAULT: The message processor is disabled at server startup.
Number of threads
The number of concurrent threads the triggered cache manager server spawns when sending completion messages to this acknowledgment target. The value must be greater than 0 and less than 231 (or 2.147x109).
Server name
The name of the triggered cache manager server for which the description is associated (left justified and padded with blanks if necessary).

ATDG0200 format

Offset Type Field
Dec Hex
0 0   Everything from ATDG0100 format
96 60 Char(256) HTTP IP interface
352 160 Binary(4) HTTP TCP port
356 164 Binary(4) Offset to HTTP URI root
360 168 Binary(4) Length of HTTP URI root
364 16C Binary(4) HTTP keepalive
368 170 Binary(4) Timeout
    Char(*) HTTP URI root

ATDG0200 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) or dotted address (for example, 192.168.3.57).
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.

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.
HTTP TCP port
The TCP port of HTTP Server acknowledgment target. The value must be greater than 0 and less than 65536.
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 defines the root of this acknowledgment target (left justified and padded with blanks if necessary).
Note: All completion message requests sent to the acknowledgment target are prepended with this path.
Length of HTTP URI root
The length of the information for the HTTP URI root entry.
Offset to HTTP URI root
The offset from the beginning of the request variable to the HTTP URI root data, in bytes.
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 231 (or 2.147x109), 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.

ATDP0210 format

Offset Type Field
Dec Hex
0 0   Everything from ATDG0100 format
96 60 Char(32) HTTP host
128 80 Binary(4) HTTP TCP port
132 84 Binary(4) Offset to HTTP URI root
136 88 Binary(4) Length of HTTP URI root
140 8C Binary(4) HTTP keepalive
144 90 Binary(4) Timeout
    Char(*) HTTP URI root

ATDP0210 format field descriptions

HTTP host
The name of a host description referenced by the acknowledgment target description and used, at server startup, to obtain information about the system hosting an HTTP server accepting completion messages. The value must be a host description name (left justified and padded with blanks if necessary).
Note: See HTTP TCP port for more information. The referenced host description may or may not currently exist. It is possible that it was removed or associated with a different triggered cache manager server after this acknowledgment target description was last modified.
HTTP keepalive
Specifies if connections to HTTP Server are kept open for reuse after data transfer. 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: The connection is kept open after data transfer.
0 QZHT_NO, QZHT_FALSE, QZHT_DISABLED: The connection is closed after data transfer.
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.
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 defines the root of this acknowledgment target (left justified and padded with blanks if necessary).
Note: All requests to send completion messages to this acknowledgment target are prepended with this path.
Length of HTTP URI root
The length of the information for the HTTP URI root entry.
Offset to HTTP URI root
The offset from the beginning of the request variable to the HTTP URI root data, in bytes.
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 231 (or 2.147x109), or equal to one of the special values described below.

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.

Error messages

TCM7001 E
User &1 is not authorized.
TCM7030 E
Severe error occurred while addressing parameter list.
TCM7032 E
Receiver variable format is not valid.
TCM7034 E
Length of receiver variable is not valid for the specified format.
TCM7035 E
Server parameter is not valid.
TCM7036 E
Description parameter is not valid.
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.
TCM7290 E
&1 &2 was not found for triggered cache manager server &3.