HXP Client

In order for an application to call procedures in a remote application and receive the requested data, it should have an HXP client created and installed.

Creating a client

Creating a HXP client is very easy and straightforward by using a ready made library. Below is an explanation on how to create a basic HXP client based on the Incutio IXR library for the php programming language. Other libraries for other languages should have similar methods for creating the client.

Basic Client Construction

HXP client based on IXR library allows you to make requests to HXP servers using the IXR_Client class. Before you make a connection you will need to know the host, path and port of the HXP server you wish to communicate with, and know which method on the server you wish to access. The HXP methods are listed in the Procedure Call Dictionary (HXP-PCD) which is published for public use. You can see the published Dictionaries here.

First you will need to create an IXR_Client object. You must supply the details of the server you wish to connect to when you create the object, either as a URL or as a hostname, path and port:

// Specifying a HXP server by URL (port 80 is assumed):
$client = new IXR_Client('http://www.care2x.net/foundry/modules/hxp/server.php');

// Specifying a HXP server by host, path and port
$client = new IXR_Client('www.care2x.net', '/foundry/modules/hxp/server.php', 80);

The next step is to make your HXP call using the query() method. The method accepts a HXP procedure name with a variable number of arguments, which will be passed to the HXP server along with the request. The query() method returns true or false depending on whether or not your request has been successful. Should your request fail the getErrorCode and getErrorMessage methods will usually provide a more detailed explanation of what went wrong.

// Create the header and supply the username and password
$header['usr']='hxp';
$header['pw']='hxp';

// Create the PID of the person for the second argument
$PID=10000002;

if (!$client->query('Person.Basic', $header, $PID)) {
    die('Something went wrong - '.$client->getErrorCode().' : '.$client->getErrorMessage());
}

Presuming the method was successful, you can access the data returned by the HXP server using the getResponse() method. This will return a single value or an array of values, depending on the data structure returned by the server.

echo $client->getResponse();

So far, so good. Now let's try for something a bit more complicated. The care2x.net has set up an example HXP server that interfaces with Care2x HIS, an integrated hospital information system. Let's see what it knows about the person with a PID (Person Identifier) of 10000000.

We want to see only some of the basic data of the person and after scanning the Procedure Call Dictionary we found the Person.Basic to be the proper procedure name for the purpose. (A sample code for Python language can be seen here)


// Create the client object
$client = new IXR_Client('http://www.care2x.net/foundry/modules/hxp/server.php');

// Create the header and supply the username and password
$header['usr']='hxp';
$header['pw']='hxp';

// Create the PID of the person for the second argument
$PID=10000000;

// Run a query for PHP
if (!$client->query('Person.Basic', $header, $PID)) {
    die('Something went wrong - '.$client->getErrorCode().' : '.$client->getErrorMessage());
}

// Get the result
$response = $client->getResponse();

// Display the result
echo '<TABLE BORDER=0>';
while(list($x,$v) = each($response)){
	echo '<TR><TD>'.$x.'</TD><TD>'.$v.'</TD></TR>';
}
echo '</TABLE>';

You should see something that looks like this:


 pid    10000000
 title    Lord
 name_first    Coon
 name_last    Ty
 name_2    William
 name_3    
 name_middle    Heinrich
 name_maiden    
 name_others    James Gone
 date_birth    2003-12-31
 sex    m
 addr_str    New Hamshire
 addr_str_nr    54
 addr_zip    5456
 addr_citytown_nr    1
 photo_filename

So far, everything looks fine. We were able to get the basic data of the person using our previous knowledge of his PID number. Now, let's say we do not know any PID numbers at all. What should we do? Well, we can try listing the persons available. After consulting the Procedure Call Dictionary (PCD), we found the Person.List procedure name.


// Create the client object
$client = new IXR_Client('http://www.care2x.net/foundry/modules/hxp/server.php');

// Create the header and supply the username and password
$header['usr']='hxp';
$header['pw']='hxp';


// Run a query for PHP
if (!$client->query('Person.List', $header)) {
    die('Something went wrong - '.$client->getErrorCode().' : '.$client->getErrorMessage());
}

// Get the result
$response = $client->getResponse();

// Display the result
echo '<TABLE BORDER=0>';

echo "<TR>
	<TD> PID </TD>
	<TD> Family name </TD>
	<TD> First name </TD>
	<TD> Date of birth </TD>
	<TD> Zip </TD>
	<TD> Sex </TD>
	<TD> Death date </TD>
	<TD> Record status </TD>
	</TR>";
	
while(list($x,$v) = each($response)){
	echo "<TR>";
	while(list($y, $z) = each($v)){
		echo '<TD>'.$v.'</TD>';
	}
	echo "</TR>";
}

echo '</TABLE>';

Now, you should see something that looks like this:




 PID 
 Family name 
 First name 
 Date of birth 
 Zip 
 Sex 
 Death date 
 Record status 


 10000000   
 Ty   
 Coon   
 2004-01-12   
 m   
 5456   
 0000-00-00   
 normal   
 10000001   
 test   
 test   
 2002-12-01   
 m   
 12345   
 0000-00-00  
 normal   


 10000002   
 becker   
 walter   
 1966-04-05   
 m   
 2222   
 0000-00-00   
 normal   


 10000003   
 Khan   
 Zamir   
 1972-03-02   
 m   
 46445456   
 0000-00-00   
 normal   


 10000004   
 Caballero   
 pepe   
 1978-10-12   
 m   
 35567   
 0000-00-00   
 normal   


 10000005   
 HXP   
 Client   
 2002-03-01   
 m  
 Z9993   
 0000-00-00   
 normal   


 10000006   
 Khan   
 Anuar   
 1977-07-23   
 m   
 435895   
 0000-00-00   
 normal

Header arguments and authentication data

Each procedure call requires a compulsory heading argument as the first parameter (shown as the $header variable on the above examples). This parameter is an indexed array (RPC's struct) and must contain by default the following keys and data:

Key Data

usr Username

pw Password

emergency (integer) 1
(If the call is done in "emergency". Can be left unset in normal cases.)

When the header argument is missing, the query will receive an error code 1000 and the error message "_ERROR_AUTH_BADHEADER".

By default, the "emergency" key can be either left unset or set to the 0 value or empty character.

Key Data

lang Language code

sid session ID

version HXP version (e.g. 1.0, 1.0.3)

The availability of the optional keys can be detected either on the fly or during configuration by using the following system procedure calls:

	system.Header.Keys.lang
	system.Header.Keys.sid
	system.Header.Keys.version

If the key is supported by the remote application, the query should receive the value of integer 1.

Other keys and data may have been added to the remote application according to the its design but these are not considered standard and should be properly documented and published. It is always important to consult the documentation of the remote HXP server. To be on the safe side, it is good to use only the published standard keys.

Debugging with IXR library

Should you need to debug your client procedure calls at any time you can do so with the debug flag:

$client = new IXR_Client('http://www.care2x.net/foundry/modules/hxp/server.php');

$client->debug = true;

// Create the header and supply the username and password
$header['usr']='hxp';
$header['pw']='hxp';

if (!$client->query('Person.Basic', $header, 10000000)) {
    die('Something went wrong - '.$client->getErrorCode().' : '.$client->getErrorMessage());
}

With the debug flag turned on, IXR_Client will display the full contents of all outgoing and incoming HXP messages.