Retrieve Triggered Cache Manager Data Source Description (QzhtRtvTCMDataSourceDesc) 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 QzhtRtvTCMDataSourceDesc API to retrieve information from data source 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

*IOSYSCFG special authority

Required parameter group

receiver variable: OUTPUT: CHAR(*)
The variable used to return data source description information. See Data source 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:

DSDG0100: Basic information format for data source description.
DSDG0200: Detailed information format for an *IFS type data source description.
DSDG0300: Detailed information format for an *HTTP1 type data source description.
DSDG0310: Detailed information format for an *HTTP2 type data source description.

See Data source description formats for more information.

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

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

DSDG0100 format

When the data source description type is unknown, use the DSDG0100 format and the basic information (including data source type) is returned. You may then use the returned data source type to call the API again and return detailed information about the data source description using one of the detailed information formats.

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)	Data source description name
72	48	Char(10)	Data source type
82	52	Char(2)	Reserved
84	54	Binary(4)	Default property
88	58	Binary(4)	Number of threads

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

Data source description name: The data source description name (left justified and padded with blanks if necessary).

Data source type

The data source description type (left justified and padded with blanks if necessary). The returned value is 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

Default property

Indicates whether the description is the current default data source description for the triggered cache manager server specified in Server name. The returned value equals to one of the special values described below.

Special values and their meanings are as follows:

1	QZHT_YES, QZHT_TRUE, QZHT_ENABLED: The description is the current default for this server.
0	QZHT_NO, QZHT_FALSE, QZHT_DISABLED: The description is not the current default.

Number of threads: The number of concurrent threads the triggered cache manager server spawns when processing requests that receive data from this data source. The value must be greater that 0 and less than 2³¹ (or 2.147x10⁹).

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

DSDG0200 format

Offset		Type	Field
Dec	Hex	Type	Field
0	0		Everything from DSDG0100 format
92	5C	Binary(4)	Offset to local directory root
96	60	Binary(4)	Length of local directory root
		Char(*)	Local directory root

DSDG0200 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 data source (left justified and padded with blanks if necessary).
Note: All file requests from this data source have this path prepended to the file name, even if an absolute path for the file is specified.

Offset to local directory root: The offset from the beginning of the receiver variable to the Local directory root data, in bytes.

DSDG0300 format

Offset		Type	Field
Dec	Hex	Type	Field
0	0		Everything from DSDG0100 format
92	5C	Char(256)	HTTP IP interface
348	15C	Binary(4)	HTTP TCP port
352	160	Binary(4)	Offset to HTTP URI root
356	164	Binary(4)	Length of HTTP URI root
360	168	Binary(4)	HTTP keepalive
364	16C	Binary(4)	Timeout
		Char(*)	HTTP URI root

DSDG0300 format field descriptions

HTTP IP interface: The IP host name or address of the system hosting an HTTP server data source (left justified and padded with blanks if necessary). The returned value is either an IP host name (for example, server.mycompany.com) or dotted IP 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

Indicates whether the triggered cache manager server attempts to keep connections to HTTP Server open for reuse after data is transferred. The returned value equals one of the special values described below.

Special values and their meanings are as follows:

1	QZHT_YES, QZHT_TRUE, QZHT_ENABLED: The server attempts to keep connections open after data transfer.
0	QZHT_NO, QZHT_FALSE, QZHT_DISABLED: The server closes each connection after data transfer.

HTTP TCP port: The TCP listening port number used by HTTP Server data source. The value returned is greater than 0 and less than 65536.
Note: The returned TCP port number is used in combination with the IP host name or address returned in HTTP IP interface to establish communication with HTTP Server data source.

HTTP URI root: HTTP Server URI path that defines the root for this data source (left justified and padded with blanks if necessary).
Note: All requests for files from this data source 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 returned for the HTTP URI root entry.

Offset to HTTP URI root: The offset from the beginning of the receiver 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 2³¹ (or 2.147x10⁹), 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.

DSDG0310 format

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

DSDG0310 format field descriptions

HTTP host: The name of the host description referenced by the data source description and used, at server startup, to obtain information about the system hosting an HTTP Server data source. The returned value is 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 the data source description was last modified.

HTTP keepalive

Special values and their meanings are as follows:

1	QZHT_YES, QZHT_TRUE, QZHT_ENABLED: The server attempts to keep connections open after data transfer.
0	QZHT_NO, QZHT_FALSE, QZHT_DISABLED: The server closes each connection after data transfer.

HTTP TCP port: The TCP listening port number used by HTTP Server data source. The returned value is greater than 0 and less than 65536.
Note: The returned TCP port number is used in combination with the IP host name or address returned in HTTP host to establish communication with HTTP Server data source.

HTTP URI root: HTTP Server URI path that defines the root for this data source (left justified and padded with blanks if necessary).
Note: All requests for files from this data source 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 returned for the HTTP URI root entry.

Offset to HTTP URI root: The offset from the beginning of the receiver variable to the HTTP URI root data, in bytes.

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.

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.