Click here to view and discuss this page in DocCommentXchange. In the future, you will be sent there automatically.

SQL Anywhere 11.0.0 » QAnywhere » Creating QAnywhere Applications » Server management requests » Administering connectors with server management requests

 

Monitoring connectors

To obtain information about connectors, write a special kind of server management request called a client status request. It contains a <ClientStatusRequest> tag that uses one or more <request> tags containing the information necessary to register the request.

Your client status request can obtain reports about connectors in several ways:

  • Make a one-time request.
  • Register a State Change Listener to have a report sent whenever the connector's state changes.
  • Register an Error Listener to have a report sent whenever an error occurs on the connector.

In addition, you can schedule a report to be sent at certain times or intervals.

ClientStatusRequest tag

To get information about connectors, use <ClientStatusRequest>.

A client status request is composed of one or more <request> tags containing all the necessary information to register the request.

<ClientStatusRequest> subtag Description
<request> Groups information in requests.
request tag for client status requests

In the <request> tag, use an optional <replyAddr> tag to specify the return address for each report generated as a result of this request. If this tag is omitted, the default return address of reports is the reply address of the originating message.

Use an optional <requestId> to add a label for the request that is included in each report. When you register multiple requests, or when you delete or modify requests, the ID makes it possible to distinguish which reports were generated from a particular request.

To specify a list of connectors for the request, include one or more <client> tags, each with one connector address. In the case of a one-time request, all of the connectors are included in the report. In the case of an event listener request, the server listens to each of these connectors.

To specify that event details should be made persistent during any server downtime, specify the <persistent> tag. This tag does not require any data and can be of the form <persistent/> or <persistent></persistent>.

You can optionally specify a list of events by including one or more <onEvent> tags with one event type per tag. If these tags are omitted, the client status request produces a one-time request. Otherwise, the client status request registers event listeners for the specified events.

<request> subtags for client status requests Description
<client> You can include one or more <client> tags, with one connector address per tag. In the case of a one-time request, all of the connectors listed are included in the report. In the case of an event listener request, the server begins to listen to each of these connectors.
<onEvent> Specifies the events upon which the server should generate reports. You can include one or more <onEvent> tags, with one event type per tag. If these tags are omitted, the Client Status Request produces a one-time request. Otherwise, the Client Status Request is used to register event listeners for the specified events.
<persistent> Specifies that the details information in this Client Status Request should be made persistent in the server database.
<replyAddr> Specifies the return address for each report generated as a result of this request. If this tag is omitted, the default return address of reports is the reply address of the originating message.
<requestId> A label for the report. This value is used as a label for the request and is included in each report generated as a result of this request. This makes it possible to distinguish which reports were generated from a particular request when multiple requests have been registered and to delete or modify outstanding requests.
<schedule> See Server management request parent tags.
One-time client status requests

You create a one-time request by omitting <onEvent> tags from the client status request. In this case, a single report is generated that contains the current status information for each connector specified in the client status request.

The following XML message omits the <onEvent> tag and so is an example of a one-time request. It generates a single report containing the current status information for each connector specified in the <ClientStatusRequest> tag.

<?xml version="1.0" encoding="UTF-8"?>
<actions>
 <ClientStatusRequest>
  <request>
   <replyAddr>ianywhere.connector.beajms\q11</replyAddr>
   <requestId>myOneTimeRequest</requestId>
   <client>ianywhere.server</client>
   <client>ianywhere.connector.beajms</client>
  </request>
 </ClientStatusRequest>
</actions>
On-event client status requests

To specify events for which you want the QAnywhere Server to generate status reports, include one or more <onEvent> tags in your client status request. Unlike one-time requests, the server does not immediately respond to the request, but instead begins listening for events to occur. Each time one of these events is triggered, a report is sent containing information about the connector that caused the event.

The following events are supported for on-event requests:

Event When it occurs
open A closed connector is opened.
close A previously opened or paused connector is closed.
statusChange The status of the connector is changed from one state to another. Possible states are open and close.
error An unexpected error is thrown by the connector.
fatalError An unhandled fatal error is thrown by the connector.
none This never occurs. This effectively removes all previous event watches from the connector.

In the following example, the connector with address ianywhere.connector.beajms\q11 is sent a status report each time the server connector changes its status or generates an error.

<?xml version="1.0" encoding="UTF-8"?>
<actions>
 <ClientStatusRequest>
  <request>
   <replyAddr>ianywhere.connector.beajms\q11</replyAddr>
   <requestId>myEventRequest</requestId>
   <client>ianywhere.server</client>
   <onEvent>statusChange</onEvent>
   <onEvent>error</onEvent>
  </request>
 </ClientStatusRequest>
</actions>
Multiple simultaneous requests

Each return address can have its own set of event listeners for any number of connectors, including the server connector. Adding an event listener to a connector does not disturb any other event listeners in the server (except possibly one that it is replacing).

Request replacement

If you add an event listener to a connector that already has an event listener registered to it by the same return address, it replaces the old listener with the new one. For example, if a statusChange listener for connector abc is registered to address x/y and you register an error listener for abc to address x/y, abc no longer responds to statusChange events.

To register more than one event to the same address, you must create a single request with more than one <onEvent> tag.

Removing a request

If an event listener for a connector is registered to an address, you can remove the event listener by providing another client status request from the same address with the "none" event specified.

In the following example, all event listeners are removed for the server connector registered to the address ianywhere.connector.beajms\q11:

<?xml version="1.0" encoding="UTF-8"?>
<actions>
 <ClientStatusRequest>
  <request>
   <replyAddr>ianywhere.connector.beajms\q11</replyAddr>
   <client>ianywhere.server</client>
   <onEvent>none</onEvent>
  </request>
 </ClientStatusRequest>
</actions>
Persistent client status requests

To specify that the details of a request are saved into the global properties table on the message store (where they can be automatically reinstated after a server restart), include the <persistent> tag in a client status request. Persistence can be used with scheduled events and event listeners, but not one-time requests. The rules for adding and removing persistent requests are similar to those for regular requests, except that scheduled events and event listeners cannot be added separately. Instead, when adding a persistent request, the client must specify all event listeners and schedules for a particular connector/reply address pair in the same request.

The following example adds the event listener and schedule to ianywhere.connector.myConnector and makes them persistent. It also overwrites any previous persistent requests from this connector/reply address pair. A report is sent every half hour, as well as any time a connector status change occurs.

<?xml version="1.0" encoding="UTF-8"?>
<actions>
 <ClientStatusRequest>
  <request>
   <replyAddr>ianywhere.connector.beajms\q11</replyAddr>
   <client>ianywhere.connector.myConnector</client>
   <onEvent>statusChange</onEvent>
   <schedule>
    <everyminute>30</everyminute>
   </schedule>
   <persistent/>
  </request>
 </ClientStatusRequest>
</actions>
Event listener persistence

If a connector is closed, any event listeners it has registered to its address persist in the server until the server is shut down. If the connector is reopened, the stored event listeners become active again.

Connector states

A connector can be in one of two states:

  • running   The connector is accepting and processing incoming and outgoing messages. This state is reflected in the connector property ianywhere.connector.state=1.

  • not running   The connector is not accepting or processing incoming or outgoing messages. When the connector state is changed to "running" the connector is initialized from scratch. This state is reflected in the connector property ianywhere.connector.state=2.

For information about how to change the connector state, see Modifying connectors.


Client status reports