Difference between revisions of "VistA RPC"

Latest revision as of 00:43, 14 February 2012

VistA RPC is a VA developed protocol that allows for remote procedure calls against VistA. Most famously, CPRS uses the RPC mechanism as its primary communication method.

Protocol Definition

The protocol definition is still to be found in detail, but the RPC Standard Header and Message Parameters are documented at: Broker msg specs A Microsoft word document with the same information is available at: http://mirrors.medsphere.org/pub/downloads.va.gov/files/FOIA/Software/VistA_FOIA_Historical_Files/VISTA_FOIA_RELEASES_BEFORE_2008/XWB-RPC%20Broker/PROGRAMS/broker%20msg%20specs.doc

Delphi Implementation

The Delphi Components and Published Property and Methods are documented at:

|RPC Broker: Getting Started

CPRS is written in delphi and relies on a delphi library to make VistA RPC calls. This library is documented in RPC BROKER: Getting Started with the Broker Development Kit (BDK) which you can download from the VA.

Return types

There five different values that can be returned by a VistA RPC call.

• Single Value : a single value is returned
• Array : a small array of values is returned
• Word Processing : a stream text with carriage returns is returned
• Global Array: This type is useful for returning large amounts of data to the client, where using the ARRAY type can exceed the symbol table limit and crash your RPC.
• Global Instance: Set the return parameter to a closed global reference.

Obviously the last two are special cases that are very specific to MUMPS.

Calling methods

In order to call an RPC, you must give it arguments or parameters which live in a "Params" object. From the manual:

RPCBroker1.Param[0].Value := '10/31/97';
RPCBroker1.Param[0].PType := literal;
RPCBroker1.Param[1].Mult['"NAME"'] := 'SMITH, JOHN';
RPCBroker1.Param[1].Mult['"SSN"'] := '123-45-6789';
RPCBroker1.Param[1].PType := list;

This shows how to pass a single variable, or an array.

Then set the RPC to execute

RPCBroker1.RemoteProcedure:='A6A LIST';

Then send it...

try
    RPCBroker1.Call;
except
  On EBrokerError do
    ShowMessage('A problem was encountered communicating with the server.');
end;

You should get back the results in the Results property like so??

RPCBroker1.Results[0].Value 

not sure how multiple values are stored...

JavaLink Implementation

no idea.

M2M Broker Implementation

TCP/IP information

If you are trying to access VistA from behind a firewall you might have some problems, here is a complete description of what those problems might be and some troubleshooting tips.

Like FTP VistA RPC is a multiple port protocol. There are two stages in the VistA RPC protocol

• CPRS -> VistA. source port is random. Destination port is whatever VistA is configured to listen to usually in the 9211 range. The system will attempt to login with the most modern VistA RPC implementation which is marked by the '[XWB]' in the protocol. Failing that the system will increase the source port by one and attempt to connect using the older version of the protocol which begins with '{XWB}'
• VistA -> CPRS After receiving the initial connection, VistA will attempt to call the client back. VistA will choose a random port? in the low range i.e. 1250 and attempt to connect to the CPRS client machine on the original CPRS sourceport +1. So if CPRS originally contacted VistA from 1586, then VistA will try to call back to destination port 1587. If VistA cannot get through to the client it will try and change its source port. So it will try 1250 first, then 1251 then 1252 and so on.

The "callback" nature of the RPC protocol is a problem for a NAT environment. For instance when a network is hidden behind a single IP address, the outgoing connection to VistA from inside the network is understood by the NAT device. The "callback" is the problem without some mechanism to associate the the callback to the original connection the NAT device does not know which host on the NATed network to send the new traffic to. However, the callbacks do enable a certain amount of implicit security. Because the RPC protocol is a "single packet" protocol, it is particularly vulnerable to spoofing. Apparently there is a setting within VistA to force "same-port" operation.

Links

University of Kuopio in Finland has written an RAD tool making use of the delphoi RPCBroker system called FixIT. HardHats has some FixIT information