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.

File 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:

  1. Create the zero-byte file.
  2. Wait for the file to have a non-zero size.
  3. Read the file contents.
  4. Delete the file.

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.

Database Monitoring

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 10 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
ParameterValue
:ServiceName The short name of the service, HL7Script or HL7Trans.
:ServiceID See Multiple Service Instances. Blank if not configured.
:ConnectionNameThe 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.

Schema Example

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

Return to Top