Change Triggered Cache Manager Host Description (QzhtChgTCMHostDesc) 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

The QzhtChgTCMHostDesc API changes host descriptions associated with triggered cache manager servers. Changes made to host descriptions are utilized by all data source, cache target, and acknowledgment target descriptions referencing them the next time the servers are started.

The QTCM/H(QZHTINCONF) header file includes ILE C prototypes for this API.

Authorities and locks

Required parameter group

request variable
INPUT: CHAR(*)

The variable used to pass information used to change a host description.

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 request variable data. The following values must be used:

  • HSDP0100: Basic information format for a host description.
server name
INPUT: CHAR(32)

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

description name
INPUT: CHAR(32)

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

error code
I/O: CHAR(*)

The structure in which to return error information.

HSDP0100 format

Offset Type Field
Dec Hex
0 0 Char(32) Server name
32 20 Char(32) Host description
64 20 Binary(4) Default property
68 44 Binary(4) IP interface

Field descriptions

Default property
Specifies whether the description is to become the default host 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) and the description is not currently the default description, the default property on the current default host description, if any, are set to 0 (QZHT_NO) and this description takes over the default role. The default value is –2 (QZHT_NO_CHANGE).

Special values and their meanings are as follows:

1 QZHT_YES, QZHT_TRUE, QZHT_ENABLED: The description is to become the default host description for this server.
-1 QZHT_DEFAULT: The default value is used.
-2 QZHT_NO_CHANGE: The current value is not changed.
Host description name
The name used by the host description (left justified and padded with blanks if necessary). The value must be a description name, or one of the special values described below.

Special values and their meanings are as follows:

*SAME
QZHT_NO_CHANGE: The current name is not changed.
Note: Host description name must be unique for each triggered cache manager server. If the name is changed while the description is referenced by data source, cache target, or acknowledgement target descriptions, they too are changed to reference the new name.
IP interface
The IP host name or address of the computer system hosting servers used by the triggered cache manager server (left justified and padded with blanks if necessary). The value must specify a host name (i.e.: server.mycompany.com), dotted address (i.e.: 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 systems 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 current value is not changed.
Server name
The name used to identify the triggered cache manager server with 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 which 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 it is referenced by other descriptions.

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 format specified.
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 servers &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.
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.
TCM72C3 E
Value passed at offset &1 is not valid.
TCM74C0 E
Triggered cache manager server name is not valid.