Retrieve Triggered Cache Manager Cache Target Description (QzhtRtvTCMCacheTargetDesc) 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 QzhtRtvTCMCacheTargetDesc API to retrieve information from cache 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 cache target description information. See Cache 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:

  • CTDG0100: Basic information format for a cache target description.
  • CTDG0200: Detailed information format for an *IFS type cache target description.
  • CTDG0300: Detailed information format for an *HTTP1 type cache target description.
  • CTDG0310: Detailed information format for an *HTTP2 type cache target description.
  • CTDG0500: Detailed information format for an *ECCP1 type cache target description.
  • CTDG0510: Detailed information format for an *ECCP2 type cache target description.
Note: See Cache target description formats for more information.
server name
INPUT: CHAR(32)

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

description name
CHAR(32)

The name used to identify which cache target 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.

CTDG0100 format

Note: When the cache target description type is unknown, use the CTDG0100 format and the basic information (including cache target type) is returned. You may then use the returned cache target type to call the API and return detailed information about the cache target description (using one of the detailed information formats).
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) Cache target description name
72 48 Char(10) Cache target type
82 52 Char(2) Reserved
84 54 Binary(4) Default property
88 58 Binary(4) Number of threads
92 5C Binary(4) Initial state

CTDG0100 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.
Cache target description name
The cache target description name (left justified and padded with blanks if necessary).
Cache target type
The cache target description type (left justified and padded with blanks if necessary). The returned value equals one of the special values below.

Special values and their meanings are as follows:

*IFS
QZHT_IFS_TYPE
*HTTP1
QZHT_HTTP_TYPE1
*HTTP2
QZHT_HTTP_TYPE2
*ECCP1
QZHT_ECCP_TYPE1
*ECCP2
QZHT_ECCP_TYPE2
Default property
Specifies if the new description is a default cache 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).
1 QZHT_YES, QZHT_TRUE, QZHT_ENABLED: The description is a default cache target description for this server.
0 QZHT_NO, QZHT_FALSE, QZHT_DISABLED: The description is not a default cache target description.
Note: Multiple default cache target descriptions are possible.
Initial state
Specifies the state that the triggered cache manager server request processor, for this cache target, is in at server startup. The value must equal one of the special values described below.
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.
Number of threads
The number of concurrent threads the triggered cache manager server spawns when processing requests sent to this cache target. The value must be greater that 0 and less than 231 (or 2.147x109).
Server name
The name of the triggered cache manager server from which the configuration information is retrieved (left justified and padded with blanks if necessary).

CTDG0200 format

Offset Type Field
Dec Hex
0 0   Everything from CTDG0100 format
96 60 Binary(4) Offset to local directory root
100 64 Binary(4) Length of local directory root
    Char(*) Local directory root

CTDG0200 format field descriptions

Length of local directory root
The length of the information for the Local directory root entry.
Local directory root
The path to the local file system directory that defines the root for this cache target (left justified and padded with blanks if necessary).
Note: All file requests send to the cache target have this path prepended to the file name, even if an absolute file path is specified.
Offset to local directory root
The offset from the beginning of the receiver variable to the Local directory root data, in bytes.

CTDG0300 format

Offset Type Field
Dec Hex
0 0   Everything from CTDG0100 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

CTDG0300 format field descriptions

HTTP IP interface
The IP host name or address of the system hosting an HTTP server cache target. The value must be a host name (for example, server.mycompany.com), dotted address (for example, 192.168.3.57) (left justified and padded with blanks if necessary).
Note: See HTTP TCP port for more information.
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.
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 the IP host name or address in HTTP IP interface to establish communication with HTTP Server cache target.
HTTP URI root
The path of HTTP Server URI that is the root of this cache target (left justified and padded with blanks if necessary).
Note: All file requests from this cache target have this path inserted into the URI, even if an absolute file path is specified.
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.

CTDG0310 format

Offset Type Field
Dec Hex
0 0   Everything from CTDG0100 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

CTDG0310 format field descriptions

HTTP host
The name of a host description associated with the triggered cache manager server that is referenced by the new cache target description and used later, at server startup, to obtain information about the system hosting an HTTP server cache target. 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 cache target description was last modified.
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.
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 the IP host name or address in HTTP host to establish communication with HTTP Server cache target.
HTTP URI root
The path of HTTP Server URI that defines the root of this cache target (left justified and padded with blanks if necessary).
Note: All file requests from this cache target have this path inserted into the URI, even if an absolute file path is specified.
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.

CTFG0500 format

Offset Type Field
Dec Hex
0 0   Everything from CTDG0100 format
96 60 Char(32) ECCP IP interface
352 160 Char(10) ECCP TCP port
356 164 Char(2) HTTP cluster IP interface
612 264 Binary(4) HTTP cluster TCP port
616 268 Binary(4) Offset to HTTP cluster URI root
620 26C Binary(4) Length of HTTP cluster URI root
624 270 Char(256) ECCP keepalive
    Char(*) HTTP cluster URI root

CTDG0500 format field descriptions

ECCP IP interface
The IP host name or address of the backend IP interface to the network router hosting a web server cluster cache target. The value must be a host name (for example, server.mycompany.com) or dotted address (for example, 192.168.3.57) (left justified and padded with blanks if necessary).
Note: See ECCP TCP port for more information.
ECCP keepalive
Specifies if the connection to the network router is 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).
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.
ECCP TCP port
The TCP port number upon which the network router 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 the IP host name or address, in ECCP IP interface, to establish communications with the network router cache target.
HTTP cluster IP interface
The IP host name or address of the web server cluster from which the network router is hosting a cache (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).
Note: See HTTP cluster TCP port for more information.
HTTP cluster TCP port
The number of the TCP port used by the triggered cache manager server to identify a particular web server cluster cache. The value returned must be greater than 0 and less than 65536.
Note: The network router described by ECCP IP interface may host multiple web server caches. The TCP port number returned here is used in combination with the IP address returned in HTTP cluster IP interface to identify a particular web server cache when communicating with the network router.
HTTP cluster URI root
The web server cluster URI path that defines the root of this cache target (left justified and padded with blanks if necessary).
Note: All file requests sent to this cache target have this path inserted into the URI, even if an absolute file path is specified.
Length of HTTP cluster URI root
The length of the information for the HTTP cluster URI root entry.
Offset to HTTP cluster URI root
The offset from the beginning of the receiver variable to the HTTP cluster URI root data, in bytes.

CTDG0510 format

Offset Type Field
Dec Hex
0 0   Everything from CTDG0100 format
96 60 Char(32) ECCP host
128 80 Binary(4) ECCP TCP port
132 84 Char(256) HTTP cluster IP interface
388 184 Binary(4) HTTP cluster TCP port
392 188 Binary(4) Offset to HTTP cluster URI root
396 18C Binary(4) Length of HTTP cluster URI root
400 190 Binary(4) ECCP keepalive
    Char(*) HTTP cluster URI root

CTDG0510 format field descriptions

ECCP host
The name of a host description associated with the triggered cache manager server referenced by the new cache target description and used later, at server startup, to obtain information about the network router hosting a web server cluster cache target. The value must be a host description name (left justified and padded with blanks if necessary).
Note: See ECCP 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 cache target description was last modified.
ECCP keepalive
Specifies if the connection to the network router is 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).
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.
ECCP TCP port
The TCP port number upon which the network router 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 the IP host name or address, obtained at server startup, from the host description (specified in ECCP host) to establish communication with the network router cache target.
HTTP cluster IP interface
The IP host name or address of the web server cluster from which the network router is hosting a cache (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).
Note: See HTTP cluster TCP port for more information.
HTTP cluster TCP port
The TCP port number used by the triggered cache manager server to identify a particular web server cluster cache. The value must be greater than 0 and less than 65536.
Note: The network router using the address, described by ECCP host, may host multiple web server caches. The TCP port number specified here is used in combination with the IP host name or address in HTTP cluster IP interface to identify a particular web server cache when communicating with the network router.
HTTP cluster URI root
The web server cluster URI path that is used to define the root of this cache target (left justified and padded with blanks if necessary).
Note: All file requests sent to this cache target have this path inserted into the URI, even if an absolute file path is specified.
Length of HTTP cluster URI root
The length of the information for the HTTP cluster URI root entry.
Offset to HTTP cluster URI root
The offset from the beginning of the receiver variable to the HTTP cluster URI root data, in bytes.

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.