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.

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.