Change Triggered Cache Manager Publishing Rule (QzhtChgTCMPublishingRule) 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 QzhtChgTCMPublishingRule API changes publishing rules associated with triggered cache manager servers. Changes made to publishing rules are utilized by all Rule Sets that are referencing them the next time that the servers are started. 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 publishing rule.

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:

  • PRDP0100: Basic information format for a publishing rule.
server name
INPUT: CHAR(32)

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 publishing rule is changed (left justified and padded with blanks if necessary).

error code
I/O: CHAR(*)

The structure in which to return error information.

PRDP0100 format

Offset Type Field
Dec Hex
0 0 Char(32) Server name
32 20 Char(32) Publishing rule name
64 40 Binary(4) Offset to file extensions
68 44 Binary(4) Length of file extensions
72 48 Binary(4) Read from data source
76 4C Binary(4) Send data source version
80 50 Binary(4) Parse and assemble
84 54 Binary(4) Send assembled version
88 58 Binary(4) Offset to new file extension
72 5C Binary(4) Length of new file extension
    Char(*) File extensions
    Char(*) New file extension

PRDP0100 format field descriptions

File extension
A list of file extensions used to identify files that are processed according to this new publishing rule. File extensions must be listed as a string of characters, where each extension starts with a period character (.) and is separated by one or more spaces (left justified and padded with blanks if necessary). There is no default value for this entry.

If Offset to file extensions equals -2 (QZHT_NO_CHANGE), the current list of file extensions is not changed.

Note: A list of file extensions is required. The file extensions are used by trigger handlers to determine when the publishing rule applies. File names are compared to file extensions starting at the last period in the file name. Therefore, each file extension must start with a period character (.), otherwise a match is not made. For example, .html, .gif, or .event.
Length of file extensions
The length of the information for the File extensions entry.
Note: If Offset to file extensions equals 0 (QZHT_NONE) or -2 (QZHT_NO_CHANGE), this value must equal 0.
Length of new file extension
The length of the information for the New file extension entry.
Note: If Offset to new file extension equals 0 (QZHT_NONE), or -1 (QZHT_DEFAULT), this value must equal 0.
New file extension
A file extension used to rename files after they have been assembled and before they are sent to the cache targets (left justified and padded with blanks if necessary). The default value is null, indicating that files are not renamed.
Note: If the value is null, Offset to new file extension must equal 0 (QZHT_NONE), -1 (QZHT_DEFAULT), or -2 (QZHT_NO_CHANGE). If a file extension is specified, files matching any one of the file extensions listed in File extension are renamed with the file extension prior to being sent to the cache targets. An escape message is sent if a new file extension is provided and Send assembled version equals 0 (QZHT_NO).
Offset to new file extension
The offset from the beginning of the request variable to the New file extension data, in bytes. The value must be greater than 0 or equal 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 New file extension.
-2 QZHT_NO_CHANGE: The current file extension, if any, is not changed for New file extension.
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).
Offset to file extensions
The offset from the beginning of the request variable to the New file extension data, in bytes. The value must be greater than 0, or equal 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 New file extension.
-2 QZHT_NO_CHANGE: The current file extension, if any, is not changed for New file extension.
Note: An escape message is sent if Offset to new file extension is greater than 0 (indicating a new file extension has been provided) and Send assembled version equals 0 (QZHT_NO).
Parse and assemble
Specifies if files matching this publishing rule are parsed for wrappers and includes, and possibly sent through the page assembler. If the name is changed during wrapper parsing, the extension of the new name is used to determine if the file should be parsed for includes and sent through the page assembler. The value must equal one of the special values described below. The default value is 0 (QZHT_NO).

Special values and their meanings are as follows:

1 QZHT_YES, QZHT_TRUE, QZHT_ENABLED: Files matching this publishing rule are parsed and possibly sent through the page assembler.
0 QZHT_NO, QZHT_FALSE, QZHT_DISABLED: Files matching this publishing rule are not parsed.
Note: Files that are not parsed are not sent through the page assembler.
-1 QZHT_DEFAULT: The default value is used.
-2 QZHT_NO_CHANGE: The current value is not changed.
Note: An escape message is sent if Parse and assemble equals 1 (QZHT_YES) and Read from data source equals 0 (QZHT_NO).
Publishing rule name
An escape message is sent if Parse and assemble equals 1 (QZHT_YES) and Read from data source equals 0 (QZHT_NO).

Special values and their meanings are as follows:

*SAME
QZHT_NO_CHANGE_CHAR: The current name is not changed.
Note: Publishing rule names must be unique for each triggered cache manager server. They are referenced by name, from Rule Sets associated with the same server.
Read from data source
Specifies if files matching this publishing rule are read from the data source when triggered. The value must be one of the special values described below. The default value is 1 (QZHT_YES).

Special values and their meanings are as follows:

1 QZHT_YES, QZHT_TRUE, QZHT_ENABLED: Files matching this publishing rule are read from the data source when triggered.
0 QZHT_NO, QZHT_FALSE, QZHT_DISABLED: Files matching this publishing rule are not read from the data source.
Note: Not reading files from the data source is useful when triggers specify a file which is purely symbolic and need not correspond to an actual file, yet causes dependent files processing.
-1 QZHT_DEFAULT: The default value is used.
-2 QZHT_NO_CHANGE: The current value is not changed.
Send assembled version
Specifies if the assembled version of files matching this publishing rule are sent to cache targets when triggered and processed. The value must equal one of the special values described below. The default value is 0 (QZHT_NO).

Special values and their meanings are as follows:

1 QZHT_YES, QZHT_TRUE, QZHT_ENABLED: Assembled versions of files matching this publishing rule are sent to cache targets when triggered and processed.
0 QZHT_NO, QZHT_FALSE, QZHT_DISABLED: Assembled versions of files matching this publishing rule are not sent to cache targets.
-1 QZHT_DEFAULT: The default value is used.
-2 QZHT_NO_CHANGE: The current value is not changed.
Note: An escape message is sent if Send assembled version equals 1 (QZHT_YES) and Parse and assemble equals 0 (QZHT_NO).
Send data source version
Specifies if the data source version of files matching this publishing rule (the version read from the data source prior to assembly) are sent to cache targets when triggered and processed. The value must equal one of the special values described below. The default value is 1 (QZHT_YES) when Read from data source equals 1 (QZHT_YES), and 0 (QZHT_NO) when Read from data source equals 0 (QZHT_NO).

Special values and their meanings are as follows:

1 QZHT_YES, QZHT_TRUE, QZHT_ENABLED: Data source versions of files matching this publishing rule are sent to cache targets when triggered and processed.
0 QZHT_NO, QZHT_FALSE, QZHT_DISABLED: Data source versions of files matching this publishing rule are not sent to cache targets.
-1 QZHT_DEFAULT: The default value is used.
-2 QZHT_NO_CHANGE: The current value is not changed.
Note: An escape message is sent if Send data source version equals 1 (QZHT_YES) and Read from data source equals 0 (QZHT_NO).
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 be one of the special values described below. If a server name is specified which is different than the one that is currently associated, it is removed from its current association and added to 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.