The HL7Tools service config programs have a Connection Status dialog that displays the status of each active connection while the service is running. This status includes the last activity time and the count of messages processed since startup. If you wish to write your own program for monitoring the services, there are two methods available: File Monitoring and Database Monitoring.
Every few seconds, each connection thread watches for the presence of a specially named zero-byte file in the application directory. If present, the current status is written to the file. The config programs use this method for the display of the Connection Status screen.
Periodically repeat the following steps for each connection to be monitored:
Repeat as often as needed, but the services will check only when idle (between intervals) and no more often than every two seconds.
The naming convention of the file is as follows:
<ServiceName>_<ConnectionName>_StatusQuery.tmp
The filename includes a shortened service name to allow for both services to have connections with the same names. The short service name for HL7ScriptService is HL7Script, and HL7TransmitterService is HL7Trans.
Examples: HL7Script_Labs_StatusQuery.tmp, HL7Trans_ADTInbound_StatusQuery.tmp
When written, the content of the file is a single line of text in the following format:
<StatusText> [<LastActivityTime> <MessageCount>]
If the last activity time is within the last 24 hours, only the time will be displayed. If more than a day has passed since the last activity, the format is a complete ANSI date/time. If no successful message processing has taken place since the service was started, it will display as a dash (-). The message count is formatted with thousands separators.
File monitoring is always available, even if database monitoring has also been enabled.
A database may be used to capture and monitor the current status of a connection. Edit the service ini file (there is no GUI for this feature) and add an entry called StatusSQL with a SQL statement that will be run whenever the status is updated. The nature of ini files limits the SQL to a single line of text, so executing a stored procedure is suggested (see below).
If a connection is already database-enabled, that database will be used for status updates by default. If it is file-based or a different database is needed for monitoring, add an entry called StatusDB with the name of a pre-configured database connection.
If the StatusDB and/or StatusSQL entries are placed in the global section of the ini (the top part with no [Section] header) those values will be used for any connection that doesn't have its own StatusDB or StatusSQL setting. A connection-specific setting will override a global setting, including a blank.
The SQL statement will be run at startup, at shutdown, and whenever there is activity, but no more often than every two seconds. A "heartbeat" update will be run every 5 minutes when there is no recent activity to indicate the service is still working.
A number of parameters are available to the SQL:
StatusSQL Parameters | |
---|---|
Parameter | Value |
:ServiceName | The short name of the service, HL7Script or HL7Trans. |
:ServiceID | See Multiple Service Instances. Blank if not configured. |
:ConnectionName | The Connection name. |
:StatusText | The current status of the connection or "Stopped" if the service has been stopped. |
:MessageCount | The number of messages processed since startup (Int64). |
:LastActivity | The date/time of the last activity. NULL if there has been no activity since startup. |
:StartTime | The date/time the service was started. |
The following ini and schema examples were written for use with SQL Express. The SetConnectionStatus stored procedure is used to insert or update the status record for each connection.
StatusDB=HL7Tools
StatusSQL=EXEC SetConnectionStatus :ServiceName, :ServiceID, :ConnectionName, :StatusText, :MessageCount, :LastActivity, :StartTime
CREATE TABLE ConnectionStatus (
ServiceName varchar(10) not null,
ServiceID varchar(50) not null,
ConnectionName varchar(50) not null,
StatusText varchar(200),
MessageCount bigint,
LastActivity datetime,
StartTime datetime,
LastUpdate datetime,
CONSTRAINT pkConnectionStatus
PRIMARY KEY (ServiceName, ServiceID, ConnectionName)
)
GO
CREATE PROCEDURE SetConnectionStatus (
@ServiceName varchar(10),
@ServiceID varchar(50),
@ConnectionName varchar(50),
@StatusText varchar(200),
@MessageCount bigint,
@LastActivity datetime,
@StartTime datetime)
AS
BEGIN
IF EXISTS (
SELECT 1
FROM ConnectionStatus
WHERE ServiceName = @ServiceName
AND ServiceID = @ServiceID
AND ConnectionName = @ConnectionName
)
UPDATE ConnectionStatus SET
StatusText = @StatusText
, MessageCount = @MessageCount
, LastActivity = @LastActivity
, StartTime = @StartTime
, LastUpdate = CURRENT_TIMESTAMP
WHERE ServiceName = @ServiceName
AND ServiceID = @ServiceID
AND ConnectionName = @ConnectionName;
ELSE
INSERT INTO ConnectionStatus
( ServiceName
, ServiceID
, ConnectionName
, StatusText
, MessageCount
, LastActivity
, StartTime
, LastUpdate )
VALUES
( @ServiceName
, @ServiceID
, @ConnectionName
, @StatusText
, @MessageCount
, @LastActivity
, @StartTime
, CURRENT_TIMESTAMP );
END
GO