Change Triggered Cache Manager Data Source Description (QzhtChgTCMDataSourceDesc) 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 of request variable	Input	Binary(4)
3	request 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 QzhtChgTCMDataSourceDesc API to change data source descriptions associated with triggered cache manager servers. Changes made to data source descriptions are utilized by all trigger handler descriptions that reference them the next time the servers are started. 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 change a data source description. See Data source 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:

DSDP0100: Basic information format for a data source description.
DSDP0200: Detailed information format for an *IFS type data source description.
DSDP0300: Detailed information format for a *HTTP1 type data source description.
DSDP0310: Detailed information format for a *HTTP2 type data source description.

See Data source description formats for more information.

server name: The name used to identify the server for which the description is changed (left justified and padded with blanks if necessary).

description name: The name used to identify which data source description is changed (left justified and padded with blanks if necessary).

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

DSDP0100 format

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

DSDP0100 format field descriptions

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

Data source description name

The name used by the new data source description (left justified and padded with blanks if necessary).

Special values and their meanings are as follows:

*SAME: QZHT_NO_CHANGE_CHAR: The current type is not changed.

Note: Data source 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.

Data source type

The type of data source 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:

*SAME: QZHT_NO_CHANGE_CHAR: The description is not changed to a different type.

*IFS: QZHT_IFS_TYPE: The description is changed to an *IFS type data source description.

*HTTP1: QZHT_HTTP_TYPE1: The description is changed to an *HTTP1 type data source description.

*HTTP2: QZHT_HTTP_TYPE2: The description is changed to an *HTTP2 type data source description.

Note: If a specified type is different than the current type, certain information is discarded if it cannot be mapped to values for reuse by the new description type. See other data source description formats for details.

Default property

Specifies if the new description will become the default data source description for the triggered cache manager server specified in Server name. The value must equal one of the special values described below. If the value equals 1 (QZHT_YES), the default property on the current default data source description is set to 0 (QZHT_NO). This description takes over the default role. The default value is 0 (QZHT_NO).

Special values and their meanings are as follows:

1	If a specified type is different than the current type, certain information is discarded if it cannot be mapped to values for reuse by the new description type. See other data source description formats for details.
-1	QZHT_DEFAULT: The default value is used.
-2	QZHT_NO_CHANGE: The current value is not changed.

Note: Trigger handler descriptions added or changed using the *DEFAULT special value are referenced from this data source description designated as default at the time the trigger handler descriptions are added or changed.

Number of threads

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

Special values and their meanings are as follows:

-1	QQZHT_DEFAULT: The default value is used.
-2	QZHT_NO_CHANGE: The current value is not changed.

Server name

The name used to identify the triggered cache manager server to which the description is associated (left justified and padded with blanks if necessary). The value must be a server name, or one of the special values described below. If a server name is specified that is different than the one with which the description is currently associated, it is removed from its current association and added for the new server.

Special values and their meanings are as follows:

*SAME: QZHT_NO_CHANGE_CHAR: The current server association is not changed.
Note: An escape message is sent if the description is removed from its current association while being referenced by other descriptions.

DSDP0200 format

Offset		Type	Field
Dec	Hex	Type	Field
0	0		Everything from DSDP0100 format
84	54	Binary(4)	Offset to local directory root
88	58	Binary(4)	Length of local directory root
		Char(*)	Local root directory

DSDP0200 format field descriptions

Note: If the current description type is not *IFS, all information currently stored for the description, that is not mapped for one the following entries, is discarded.

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

Local directory root

The path to the local file system directory that is the root of this data source (left justified and padded with blanks if necessary). The value must be a path acceptable to the root (/) file system of the local iSeries™ system. If a path is provided, but does not specify a absolute path (does not start with / ), the path is prepended with the default path. The default path is /QIBM/UserData/TCM/{Server name} where {Server name} is the name of the triggered cache manager server as defined by Server name.

If the current type is:		Details
*IFS	use current Local directory root path	No change is made
HTTP1 or HTTP2	use current HTTP URI root path	Refers to DSDP0300 or DSDP0310 format
any other	use default path

Note: All requests for files from the data source must have this path prepended to the file name, even if an absolute path is specified for the file. If the value is null, Offset to local directory root must equal 0 (QZHT_NONE) or -1 (QZHT_DEFAULT).

Offset to local directory root

The offset from the beginning of the request variable to the Local directory root data, in bytes. The value must be greater that 0, or equal to one of the special values described 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 Local directory root.
-2	QZHT_NO_CHANGE: If the current description type is IFS, the current path for Local directory root is not changed. If the current description type is not IFS, see details for Local directory root on how current description values are mapped for reuse by the new description type.

DSDP0300 format

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

DSDP0300 format field descriptions

Note: If the current description type is not *HTTP1, all information currently stored for the description, that is not mapped for one the following entries, is discarded.

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

*SAME: QZHT_NO_CHANGE_CHAR: The following rules are used to map current description values for reuse.

If the current type is:		Details
*HTTP1	use current HTTP IP interface value	No change is made.
*HTTP2	use IP interface value from the host description currently referenced by HTTP host An exception occurs if the referenced description does not exist. Refers to the	An exception occurs if the referenced description does not exist. Refers to the DSDP0310 format.
any other	use default value

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.
-1	QZHT_DEFAULT: The default value is used.
-2	QZHT_NO_CHANGE: If the current description type is HTTP1 or HTTP2, the current value is not changed. If the current description type is not HTTP1 or HTTP2, 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.
-2	QZHT_NO_CHANGE: The following rules are used to map current description values for reuse.

If the current type is:		Details
HTTP1 or HTTP2	use current HTTP TCP port value	No change is made
any other	use default value

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 data source.

HTTP URI root

The path of HTTP Server URI that is the root of this data source (left justified and padded with blanks if necessary). The value must be a path acceptable to HTTP Server. The default path is / .

If Offset to HTTP URI root equals -2 (QZHT_NO_CHANGE), the following rules are used to map current description values for reuse:

If the current type is:		Details
*IFS	use current Local directory root path	Refers to DSDP0200 format.
HTTP1 or HTTP2	use current HTTP URI root path	No change is made
any other	use default path

Note: All file requests from this data source have this path inserted into the URI, even if an absolute path for the file is specified. If the value is null, Offset to HTTP URI root must equal 0 (QZHT_NONE), or -1 (QZHT_DEFAULT).

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.
-2	QZHT_NO_CHANGE: If the current description type is HTTP1 or HTTP2, the current path for HTTP URI root is not changed. If the current description type is not HTTP1 or HTTP2, see details for HTTP URI root on how current description values are mapped for reuse by the new description type.

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.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.
-1	QZHT_DEFAULT: The default value is used.
-2	QZHT_NO_CHANGE: If the current description type is HTTP1 or HTTP2, the current value is not changed. If the current description type is not HTTP1 or HTTP2, the default value is used.

DSDP0310 format

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

DSDP0310 format field descriptions

Note: If the current description type is not *HTTP2, all information currently stored for the description, that is not mapped to one the following entries, is discarded.

HTTP host

The name of a host description associated with the triggered cache manager server that is referenced by the new data source description and used later, at server startup, to obtain information about the system hosting an HTTP server data source. 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.

*SAME: QZHT_NO_CHANGE_CHAR: The following rules are used to map current description values for reuse.

If the current type is:		Details
*HTTP2	the description currently referenced for HTTP host is not changed	No change is made.
any other	the default host description currently associated with the triggered cache manager server 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 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.
-2	QZHT_NO_CHANGE: If the current description type is HTTP1 or HTTP2, the current value is not changed. If the current description type is not HTTP1 or HTTP2, the default value is used.

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

HTTP TCP port

Special values and their meanings are as follows:

-1	QZHT_DEFAULT: The default value is used.
-2	QZHT_NO_CHANGE: The following rules are used to map current description values for reuse.

If the current type is:		Details
HTTP1 or HTTP2	use current HTTP TCP port value	No change is made.
any other	use default value

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 data source.

HTTP URI root

The path of HTTP Server URI that is the root of this data source (left justified and padded with blanks if necessary). The value must be a path acceptable to HTTP Server. The default path is / .

If Offset to HTTP URI root equals -2 (QZHT_NO_CHANGE), the following rules are used to map current description values for reuse:

If the current type is:		Details
*IFS	use current Local directory root path	Refers to DSDP0200 format
HTTP1 or HTTP2	use current HTTP URI root path	No change is made
any other	use default path

Note: All requests for files from this data source have this path inserted into the URI, even if an absolute file path is specified. If the value is null, Offset to HTTP URI root must equal 0 (QZHT_NONE), -1 (QZHT_DEFAULT), or -2 (QZHT_NO_CHANGE). 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.
-2	QZHT_NO_CHANGE: If the current description type is HTTP1 or HTTP2, the current path for HTTP URI root is not changed. If the current description type is not HTTP1 or HTTP2, see details for HTTP URI root on how current description values are mapped for reuse by the new description type.

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.
-2	QZHT_NO_CHANGE: If the current description type is HTTP1 or HTTP2, the current value is not changed. If the current description type is not HTTP1 or HTTP2, 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.

TCM7290 E: &1 &2 was not found for triggered cache manager server &3.

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.