Both the client (within AUXDISTR) and each server (in the network manager) maintain information about which servers are currently running. This information may be accessed by reading the network status table. The information is accessed from the local client program by setting info_from.server to zero, and from a server by setting info_from to the appropriate server number. The info_about field should be set to the server number about which information is required. The rec_fetch_main(EQUAL,...) function or an equivelent should be used to read the record.
If no record is returned then the server from which information was requested did not respond. Note however that no attempt is made to contact the specified server if the client believes that it is currently off-line. For this reason you may want to force the client to attempt to contact the server by updating the network status table.
If a record is returned, then the net_mode field indicates the status of the server about which information is required and is s set to either 0 (unknown), 1 (ONLINE) or 2 (OFFLINE).
It is also possible to search through this table using rec_fetch_main(NEXT,...)and so on, but records will not be returned except those for which info_from.server is known by the local client to be online and info_about.server is known to the local client.
Refer back to Network Status table for an explanation of the various fields in this table.
The meaning of each type of server status information is as follows:
The status of each server is initially set to zero (unknown) , but is changed when a message is first sent to that server and is subsequently always either OFFLINE or ONLINE. It will be set to ONLINE unless the server fails to respond to a message, when it will be changed to OFFLINE. No further attempt will be made to contact a server with OFFLINE status (so the status will remain as OFFLINE) unless one of the following occurs:
The application forces an attempt to contact this server (see updating the network status table).
Another server indicates that the off-line server is now running again. (Only servers for which the -online option is specified on the command line will ever send such an indication).
Each server holds information about every other server, which it collates from information sent by clients during commits. A client sends its status information about the other servers at this time and this is used to determine the status of other servers. If conflicting information arrives from various clients, a report that a server is online takes precedence over a report that it is off-line (as the former implies that communication with the server took place recently, but the latter may be based on out-of-date information).
Information received from a client is retained only for a certain length of time, so that the server status is never based on old information. If no fresh information about a server arrives, its status will eventually revert to 'unknown'.
The time for which information is held defaults to five minutes, but may be altered by loading the network manager with the command tail: -stimeout nn where nn is the required timeout in seconds.
In a Multiple Resilience Configuration the network status record in which the info_from and info_about fields both zero has a special meaning. The 'net_mode' field in this record has the value ONLINE if every server about which the local client has information is currently ONLINE, and is set to OFFLINE if any one such server is OFFLINE. This allows the current integrity of the network to be tested with a single fetch on this table. The difference between this and testing the 'broken' variable is that the latter is set TRUE when a server goes off-line, but is not reset if it subsequently comes back online.
The application program can force AUXDISTR to attempt to access a server which AUXDISTR currently believes is off-line by posting to the @net_status table with a value of net_mode = ONLINE and then attempting a normal database access. Before posting The info_from field should be set to zero, the info_about field should be set to the relevant server number, and the net_mode field should be set to ONLINE.
Afterwards the @net_status table can be read as described above to discover whether the server is indeed now ONLINE.Similarly, posting @net_status with net_mode = OFFLINE forces the connection to the server to be dropped (as though the server had terminated). This may be useful if you know you are not going to access a particular server again for a while, and do not want to stay connected to it unnecessarily. Release 4.622 introduces a new net_mode STAY_OFFLINE, which you can also use to force a server offline. The difference between posting a server OFFLINE and STAY_OFFLINE as as follows: when a server is posted OFFLINE, although any current connection is dropped, AUXDISTR will reconnect to the server automatically next time a database operation should be directed to that server - rather than being truly OFFLINE the server has reverted to its initial UNKNOWN state; when a server is posted STAY_OFFLINE the server will not be reconnected automatically, the server is truly OFFLINE, exactly as it would be after a network error. AUXDISTR will normally only reconnect to the server when the application posts the the server ONLINE again. (However, if the -ONLINE mode option is used on the network manager, and AUXDISTR receives a message that the server is online, the server will be reconnected exactly as it would be after a disconnection caused by a network error)
The application program can change to error handling option by posting to the @net_status table with both key fields set to zero, and the err_mode field set to the required value. (See Network Error Handling Options with Multiple Resilience)
Other posts or deletions on this table are ignored.
Updates to the @net_status table take effect immediately, and are not postponed to the next commit() or checkpoint().