CPRS Windows Messaging Standards

Original Source of Info for this page

http://download.opensourcevista.net/downloads/CPRS_Windows_Messaging_Standards.doc

Windows Messaging

The messages generated by CPRS in Windows provide a way to coordinate programs running concurrently with CPRS. CPRS generates a message whenever certain state changes occur within the program. These state changes are: Program Startup Patient Selected, TIU Note Selected, Radiology Report Selected, Surgery Report Selected, Order Action Taken, and Program Close. Concurrently running programs can then make equivalent state changes to reflect the new state of CPRS.

The most obvious state changes a program can make is to change the current patient at the time CPRS does, and to close concurrently with CPRS. It is also possible for an imaging program to access and display an image associated with a selected TIU document or radiology report. Similarly, a program can use one of the components of a selected TIU note to take some action.

As specific needs are identified, this functionality in CPRS will be expanded by increasing the types of messages broadcast and adding the ability to act upon messages broadcast from other applications.

CPRS Message Types

Following are sample messages broadcast by the CPRS Windows executable, followed by their current definitions. Note that there are two different messages shown in each sample section, one which includes the user's domain, and one which does not. The shorter message is the old version, with the domain being added in later CPRS versions. Both types of message are now broadcast simultaneously to insure backward compatibility.

1. Program is starting:

This message is generated whenever CPRS starts up.

BEG^CPRS^^1329 
BEG^CPRS;ROX-REV.FO-SLC.MED.VA.GOV^^1329

Program is Starting fields:

Field Name	Example	Comment
Message Name	BEG	

Originating Program and Domain CPRS Both messages broadcast for backward compatibility

User DUZ	1329	

2. Program is Ending:

This message is generated whenever CPRS closes.

The close event could be the result of a specific user action such as EXIT, or it could be the result of CPRS timing out.

END^CPRS;ROX-REV.FO-SLC.MED.VA.GOV^70
END^CPRS^70

Program is Ending fields:

Field Name	Example	Comment
Message Name	END	
Originating Program and Domain	CPRS	Both messages broadcast for backward compatibility
Patient DFN	70	

3. Patient Changed:

This message is generated whenever CPRS changes the current patient. On receipt of this message, a program coordinating with CPRS can use Broker calls to change the patient it is displaying.

Example Patient Changed message:

XPT^CPRS;ROX-REV.FO-SLC.MED.VA.GOV^70^999-99-9999^2600303^PATIENT,ONE XPT^CPRS^70^999-99-9999^2600303^PATIENT,ONE

Patient Changed fields:

Field Name	Example	Comment
Message Name	XPT	
Originating Program and Domain	CPRS	Both messages broadcast for backward compatibility
Patient DFN	70	
Patient Social Security Number	999-99-9999	
Patient Date of Birth	2600303	FileMan format
Patient Name	PATIENT,ONE	

4. Report Message:

This message is generated when a TIU message is selected in the Notes, Consults, Discharge Summary, and Surgery tabs; when a radiology report or Progress Note is selected on the Reports tab; when a medicine result is selected on the Consults tab; and when a Surgery case is selected on either the Surgery or Reports tabs. A coordinating program can react to this message by taking some action based on the contents of the specific message, such as displaying an image associated with a radiology report.

Example TIU Report message:

RPT^CPRS;ROX-REV.FO-SLC.MED.VA.GOV^16^TIU^6488^^^^^^^^1
RPT^CPRS^16^TIU^6488^^^^^^^^1

TIU Report fields:

Field Name	Example	Comment
Message Name	RPT	
Originating Program and Domain	CPRS	Both messages broadcast for backward compatibility
Patient DFN	16	
Message Sub-name	TIU	
Note ID	6488	TIU document IEN in file 8925

Note has images	1 = images  0 = none	
Always located in "^" piece 13 of the message (note: not yet supported in all CPRS locations that display the text of a note)

Example Medicine Report message from Consults tab:

RPT^CPRS;ROX-REV.FO-SLC.MED.VA.GOV^16^MED^1234^^^^^^^^1
RPT^CPRS^16^MED^1234^^^^^^^^1

Medicine Report fields:

Field Name	Example	Comment
Message Name	RPT	
Originating Program and Domain	CPRS	Both messages broadcast for backward compatibility
Patient DFN	16	

Message Sub-name	MED	
Note ID	1234	Medicine result IEN in file 691.5
Note has images	1 = images 0 = none	
Always located in "^" piece 13 of the message.

Example Radiology Report message:

RPT^CPRS;ROX-REV.FO-SLC.MED.VA.GOV^16^RA^i7039389.8989-1^^^^^^^^1
RPT^CPRS^16^RA^i7039389.8989-1^^^^^^^^1

Radiology Report fields:

Field Name	Example	Comment
Message Name	RPT	
Originating Program and Domain	CPRS	Both messages broadcast for backward compatibility
Patient DFN	16	
Message Sub-name	RA	
Report/Case ID	i7039389.8989-1	Date-time stamp used for Radiology messages.
Report has images	1 = images 0 = none	
Always located in "^" piece 13 of the message.

Example TIU Report message, from "Progress Notes" on Reports tab:

RPT^CPRS;ROX-REV.FO-SLC.MED.VA.GOV^37^PN^0^7484^WASHINGTON, DC^^^^^^0
RPT^CPRS^37^PN^0^7484^WASHINGTON, DC^^^^^^0

TIU Report fields:

Field Name	Example	Comment
Message Name	RPT	
Originating Program and Domain	CPRS	Both messages broadcast for backward compatibility
Patient DFN	37	
Message Sub-name	PN	
Number of attached images	0	
Note ID	7484	TIU document IEN in file 8925
Facility	WASHINGTON, DC	Facility being queried, whether locally or via Remote Data Views
Note has images	1 = images 0 = none	
Always located in "^" piece 13 of the message.

Example Surgery Report message, from Surgery or Reports tabs:

RPT^CPRS;ROX-REV.FO-SLC.MED.VA.GOV^16^SUR^2345^^^^^^^^1
RPT^CPRS^16^SUR^2345^^^^^^^^1

Surgery Report fields:

Field Name	Example	Comment
Message Name	RPT	
Originating Program and Domain	CPRS	Both messages broadcast for backward compatibility
Patient DFN	16	
Message Sub-name	SUR	
Case ID	2345	Surgery case IEN in file 130
Case has images	1 = images 0 = none	
Not yet supported in CPRS v27.  Will be added in a future version.

5. Order Messages

CPRS also broadcasts messages to other applications when certain order actions take place. These actions include new order placed, or an existing order being discontinued, renewed, held, edited, released, or acted on in some other way. These messages all follow the same format, with the ACTION field varying depending on the specific action being taken. This message can be triggered from a variety of locations in CPRS that can perform these various actions.

Example Order message:

ORD^CPRS;ROX-REV.FO-SLC.MED.VA.GOV^37^NW^7093393;1
ORD^CPRS^37^NW^7093393;1

Order message fields:

Field Name	Example	Comment
Message Name	ORD	
Originating Program and Domain	CPRS	Both messages broadcast for backward compatibility
Patient DFN	37	
Action	NW	This field contains the action being taken that triggered this message:

NW: New order
DC: Discontinued order
RN: Renewed order
HD: Held order
XX: Changed order
RL: Released order
AC: Other unspecified action
Order ID	7093393;1	Order IEN in file 100

How to Capture Messages

An example program, written in Delphi, that displays all messages broadcast using the “VistA Event – Clinical” and 'VistA Domain Event – Clinical’ Windows message types, is presented here.

Here is the code of the main form:

Step 1: Register the 'VistA Event – Clinical' and 'VistA Domain Event – Clinical' Windows message types when the form is created

procedure TfrmMsgCatch.FormCreate(Sender: TObject);
begin
 FVistaMsg := RegisterWindowMessage('VistA Event - Clinical');
 FVistaDomainMsg := RegisterWindowMessage('VistA Domain Event - Clinical');
 mmoMessages.Lines.Clear;
end;

Step 2: Override the windows default message handler. (see procedure ‘DefaultHandler’ in the code below.)

 // do the default message handling
 inherited DefaultHandler(Message);

Step 3: Capture all 'VistA Event – Clinical' and 'VistA Domain Event – Clinical' messages that were not sent by this window. (this enables applications to send messages and not process the ones sent by themselves.

procedure TfrmMsgCatch.DefaultHandler(var Message);
var
 buf: array[0..255] of Char;
begin
 inherited DefaultHandler(Message);
 with TMessage(Message) do
 if ((Msg = FVistaMsg) or (Msg = FVistaDomainMsg)) and (wParam <> Handle) then
   begin
     GlobalGetAtomName(lParam, buf, 255);
     mmoMessages.Lines.Add(StrPas(buf));
   end;
end;

Example MsgCatch program in Delphi:  

unit MsgCatch;

interface

uses
 Windows, Messages, SysUtils, Variants, Classes, Graphics, Controls, Forms,
 Dialogs, StdCtrls;

type
 TfrmMsgCatch = class(TForm)
   mmoMessages: TMemo;
   btnClear: TButton;
   procedure FormCreate(Sender: TObject);
   procedure btnClearClick(Sender: TObject);
 private
   FVistaMsg: word;
   FVistaDomainMsg: word;
   procedure DefaultHandler(var Message); override;
 end;

var
 frmMsgCatch: TfrmMsgCatch;

implementation

{$R *.dfm}

procedure TfrmMsgCatch.FormCreate(Sender: TObject);
begin
 FVistaMsg := RegisterWindowMessage('VistA Event - Clinical');
 FVistaDomainMsg := RegisterWindowMessage('VistA Domain Event - Clinical');
 mmoMessages.Lines.Clear;
end;

procedure TfrmMsgCatch.btnClearClick(Sender: TObject);
begin
 mmoMessages.Lines.Clear;
end;

procedure TfrmMsgCatch.DefaultHandler(var Message);
var
 buf: array[0..255] of Char;
begin
 inherited DefaultHandler(Message);
 with TMessage(Message) do
 if ((Msg = FVistaMsg) or (Msg = FVistaDomainMsg)) and (wParam <> Handle) then
   begin
     GlobalGetAtomName(lParam, buf, 255);
     mmoMessages.Lines.Add(StrPas(buf));
   end;
end;

end.