Get Triggered Cache Manager Server Status (QzhtGetTCMServerStatus) 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 I/O Char(32)
5 error code I/O Char(*)
Library Name/Service Program: QTCM/QZHTINCONF
Threadsafe: Yes

The QzhtGetTCMServerStatus API retrieves the current status (or state) of triggered cache manager servers along with their respective autostart property. 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

None.

Required parameter group

receiver variable
OUTPUT: CHAR(*)

The variable used to return the information indicating the status and autostart property of triggered cache manager servers.

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:

  • INSG0100: Basic status information format for triggered cache manager servers.
server name
INPUT: CHAR(32)

The name used to identify the server for which the status information is returned (left justified and padded with blanks if necessary). The value must specify a server name, or be one of the special values described below.

The special value and its meaning is as follows:

*ALL
QZHT_ALL_CHAR: Status information for all triggered cache manager servers returned.
error code
I/O:CHAR(*)

The structure in which to return error information.

INSG0100 format

Offset Type Field
Dec Hex
0 0 Binary(4) Bytes returned
4 4 Binary(4) Bytes available
8 8 Binary(4) Offset to server entries
12 C Binary(4) Number of server entries
16 10 Binary(4) Length of server entry
Server entries
Note: The following entries are repeated for each set of server data returned.
    Char(32) Server name
    Binary(4) Autostart property
    Binary(4) Current state
    Binary(4) Local TCP port

Field descriptions

Bytes returned
The number of information bytes returned to the caller of the API.
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.
Offset to server entries
The offset from the beginning of the receiver variable to the Server entries data, in bytes.
Number of server entries
The number of entries returned in server entries.
Note: If no servers exist, the returned value equals 0 (QZHT_NONE).
Length of server entry
The length of the information for each entry in server entries.
Server name
The name of the triggered cache manager server (left justified and padded with blanks if necessary).
Autostart property
Indicates whether the new triggered cache manager server is to start when startup of *AUTOSTART triggered cache manager servers is requested. Usually *AUTOSTART servers are requested to start when TCP/IP is started, however they may also be requested via the STRTCPSVR command or QzhtStrTCMServer API.

Special values and their meanings are as follows:

1 QZHT_YES, QZHT_TRUE, QZHT_ENABLED: The server is set to start when startup of *AUTOSTART servers is requested.
0 QZHT_NO, QZHT_FALSE, QZHT_DISABLED: The server is not set to start when startup of *AUTOSTART servers is requested.
Current state
The current sate of the triggered cache manager server identified by Server name. The possible values are:
1 QZHT_INACTIVE: The server is not active.
2 QZHT_STARTING: The server is in the process of starting up.
3 QZHT_ACTIVE: The server is active.
4 QZHT_ENDING: The server is in the process of shutting down.
Local TCP port
The number of one of the TCP ports used by the triggered cache manager server. The value will be greater than 0 and less than 65536.
Note: Triggered cache manager servers use the same port number for all IP interfaces.

Error messages

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 format specified.
TCM7035 E
Server parameter is not valid.
TCM703E E
Error code parameter is not valid.
TCM70F0 E
Unknown error occurred while processing request.
TCM7390 E
TCM server instance server &1 not found.
TCM74C0 E
TCM server instance server name is not valid.