Change Triggered Cache Manager Rule Set (QzhtChgTCMRuleSet) 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 QzhtChgTCMRuleSet API changes rule sets associated with triggered cache manager servers. Changes made to rule sets are utilized by all trigger handler descriptions that are referencing them the next time that the servers are started.

Note: Triggers are sent to trigger handlers which process them according to publishing rules. Custom publishing rules are provided for the trigger handler through a rule set. If extensions of files identified in triggers match one of the extensions listed in a custom publishing rule, they are processed according to that publishing rule. If extensions do not match any of the custom publishing rules, the file is processed according to the default publishing rule.

The API is a callable service implemented as an ILE entry point within QZHTINCONF *SRVPGM in QTCM *LIB.

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

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:

  • RSDP0100: Basic information format for a rule set.
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
INPUT: CHAR(32)

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

error code
I/O: CHAR(*)

The structure in which to return error information.

RSDP0100 format

Offset Type Field
Dec Hex
0 0 Char(32) Server name
32 20 Char(32) Rule set name
64 40 Binary(4) Default property
68 44 Binary(4) Offset to publishing rules
72 48 Binary(4) Length of publishing rules
    Char(*) Publishing rules

RSDP0100 format field descriptions

Default property
Specifies if the new description is to become the default rule set 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 rule set, if any, is set to 0 (QZHT_NO). The default value is 0 (QZHT_NO).

Special values and their meanings are as follows:

1 QZHT_YES, QZHT_TRUE, QZHT_ENABLED: The description is to become the default rule set for this server.
0 QZHT_NO, QZHT_FALSE, QZHT_DISABLED: The description is not to become the default rule set.
-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, reference the rule set designated as default at the time they are added or changed.
Length of publishing rules
The length of the information for the Publishing rules entry.
Note: If Offset to Publishing rules equals 0 (QZHT_NONE) or -1 (QZHT_DEFAULT), this value must equal 0.
Offset to publishing rules
The offset from the beginning of the request variable to the Publishing rules data, in bytes. The value must be greater than 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 value is used for Publishing rules.
-2 QZHT_NO_CHANGE: The current list of publishing rules, if any, is not changed for Publishing rules.
Note: An escape message is sent if Offset to new file extension is greater than 0 (indicating that a new file extension has been provided) and Send assembled version equals 0 (QZHT_NO).
Publishing rules
A list of publishing rules associated with the triggered cache manager server referenced by the new Rule Set and used by trigger handlers, at startup, to direct how files are processed. Descriptions must be listed by name, where each name is separated by one or more spaces, and padded with blanks if necessary. The default value is null, indicating that an empty rule set is described.

If Offset to publishing rules equals 0 (QZHT_NONE) or -1 (QZHT_DEFAULT), an empty rule set is described. If Offset to publishing rules equals -2 (QZHT_NO_CHANGE), the current list of publishing rules are not changed.

Note: If the value is null, Offset to publishing rules must equal 0 (QZHT_NONE) or -1 (QZHT_DEFAULT). See Offset to publishing rules for more details. An empty rule set referenced by a trigger handler causes it to process all triggers according to the default publishing rule. An escape message is sent if any referenced description does not currently exist.
Rule set object name
The name used by the rule set (left justified and padded with blanks if necessary). The value must be a description name, or one of the special values described below.
*SAME
QZHT *SAME
Note: Rule set names must be unique for each triggered cache manager server. They are referenced, by name, from trigger handler descriptions associated with the same server.
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 being 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 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.
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 to offset &1 is not valid.
TCM74C0 E
Triggered cache manager server name is not valid.