HemaTrax® Unity Print Server

www.digi-trax.com

Improving Health and Science Through Innovative Technology

HemaTrax

Unity Print Server

HemaTrax is a registered trademark of DigiTrax Corporation

Release Notes

Build No. 13311.1338

Table of Contents

Overview........................................................................................................................................................2

Prerequisites...................................................................................................................................................2

Components...................................................................................................................................................3

HemaTrax Print Service Components.......................................................................................................3

Server Data File Directories......................................................................................................................3

HemaTrax Client Components..................................................................................................................4

Client Data Files........................................................................................................................................5

HemaTrax Print Server..................................................................................................................................6

Server Mode..............................................................................................................................................6

Service Connection Response...................................................................................................................6

Master Mode.........................................................................................................................................6

Slave Mode...........................................................................................................................................7

Standalone Mode..................................................................................................................................7

Changed Print Service Messages/Responses............................................................................................7

Get Printer Port (GPT).........................................................................................................................7

<Port Interface>...............................................................................................................................7

<Port Description>..........................................................................................................................8

Set Port (SPT).......................................................................................................................................8

<Port Number>................................................................................................................................8

<Port Interface>...............................................................................................................................8

<Port Description>..........................................................................................................................8

Version (VER)......................................................................................................................................8

Server Mode.....................................................................................................................................9

PCode.tbl Release Time...................................................................................................................9

Current/Home Directory..................................................................................................................9

New Print Service Messages.....................................................................................................................9

HemaTrax Print Server Settings..............................................................................................................10

Enhanced Security..............................................................................................................................10

"Do not print" check boxes.................................................................................................................11

Alternative Properly Identify Intended Recipient and See Circular Text...........................................11

Maximum Time Periods.....................................................................................................................11

Added ABO-Rh Codes............................................................................................................................11

Donation ID Number Flag Digit Rotation Changed...............................................................................12

New Product Label Database..................................................................................................................12

Added Unknown Volume Codes.............................................................................................................13

Unknown Volume Value Substitution Error............................................................................................13

HemaTrax Client..........................................................................................................................................14

HemaTrax Client Functionality...............................................................................................................14

Master Server Connection..................................................................................................................14

Slave Server Connection....................................................................................................................14

Standalone Server Connection...........................................................................................................14

File Migration Utility...................................................................................................................................15

New Directory Tree Structure.................................................................................................................15

Conversions of Files................................................................................................................................15

File Copies..............................................................................................................................................15

Migration Utility Restriction...................................................................................................................15

Overview

With this release of the new HemaTrax Unity Client and Print Server update there are some changes and

new features to consider. This document also touches on each of the changes and enhancements

incorporated into this new build.

Note: The information in this document is subject to change without notice.

Prerequisites

The HemaTrax software services and applications rely on a system with the following resources:

Hardware:

Computer System:

Standard Wintel system with common resources (monitor, keyboard, mouse, etc.)

Network capable (required even for Standalone operation)

Serial Port (if label printer requires it)

40 Megabytes Disk storage (Minimum)

2 Gigabytes RAM (Minimum)

CD-ROM or DVD Drive (If software is to be installed via this mechanism)

Label Printer: (SATO America CL412e* or Zebra Technologies Z4M* printer)

Network BLOOD LABELING printers must have statically assigned IPv4 addresses in order

to work properly with the HemaTrax Print Server application.

Operating System:

Microsoft Windows OS (Windows 7, Windows 2003 Server or WIndows 2008 Server)

Software Configuration:

The system may be configured to use DHCP to obtain an IP address dynamically (in the case of

Slave or Standalone operation) or must have a statically assigned IP address (when operating as a

Master server installation).

* SATO and Zebra printers must be equivalent to the model numbers provided above and must be installed with the blood

bank ready firmware supplied by Digi-Trax Corporation. A standard "off-the-shelf" printer model will not have the features

required by HemaTrax software in order to print all of the various ISBT 128 labels in FDA compliance.

Components

The new HemaTrax software is composed of some familiar components and a couple of new ones as

well. The following sections address each of the major components and how they fit into the scheme of

things.

HemaTrax Print Service Components

There is still a service application that is familiar to all implementers of the HemaTrax Print Server. The

service application has been expanded considerably to add a great deal of functionality needed by the new

client application discussed a little later. The print service components are as follows:

Component File

Name

Description of Component Function

DTiSAMlib.dll

(Deprecated)

The Digi-Trax Indexed Sequential Access Method

database engine library has been integrated with

the HemaTraxLIB.dll

HemaTraxLIB.dll

(Updated)

The Digi-Trax developed HemaTrax label

formatting language and print engine library has

been refactored and the DTiSAM functions

integrated.

HTPrtSrvr.exe

(Updated)

The Print Server service application and listening

socket interface.

HTFileMigrate.exe

The file migration utility to convert and transfer

files and tables from the previous print server or

standalone installation to the new one.

HTPrtSrvrSettings.exe

An application that provides convenient access to

and allows maintenance of the print server

settings.

IAIP.exe

The Initialize Administrator ID and Password

application, which gets executed conditionally and

only during installation.

HTServer.pdf

(Updated)

The HemaTrax print server API guide shipped

only with the Software Development Kit (SDK)

version of the HemaTrax software for interface

developers.

Table 1: Print Service components

These components are now stored in the directory path "\Program Files\HemaTrax_Unity\Print_Server".

Server Data File Directories

In releases prior to the Unity releases the data files tended to be scattered and could be found either in the

primary installation folder with the executable files or could be located in the "Data" folder found in the

application's folder located with in the "Program Files" folder. The program's data files are now organized

and all kept in a sub-directory of the "ProgramData" folder. The tree structure for the new print server is

shown in the table below:

ProgramData

│

└ HemaTrax_Print_Server

│

├ Config

│

├ Data

│

├ Format

│

├ Log

│

└ Reports

Table 2: Print Service data directory tree

The new data file organization makes more sense and will aid in making back-ups of these important

files.

HemaTrax Client Components

In releases prior the Unity releases the client program (HTClient.exe) was intended to provide some

utility functions that were not typically developed by Laboratory Information Systems (LIS) companies.

These functions included the ability to maintain printer port definitions, maintain the product label

database and to print relatively complex test labels of various formats. The HTClient.exe program has

been replaced by an entirely new application. The HemaTrax Client is now a fully functional, production

quality application that also serves as a replacement for the HemaTrax Standalone program. The

component that is included with the HemaTrax Client application is listed below:

Component File Name Description of Component Function

HTUnityClient.exe

The new HemaTrax Client application replacing the Standalone application

and the previous HTClient.exe program.

This file is stored in the path "\Program Files\HemaTrax_Unity\Unity_Client".

Beneath the path referenced above there is a tree of directories, each containing files that are static in

nature and required by the client application.

Client Data Files

All of the dynamic data files are maintained by the print service application in its data directories. The

static files used by the client program are installed in sub-directories beneath the client application's home

directory as shown in the table below:

Program Files

│

├ HemaTrax_Unity

└ Unity_Client

│

├ Data

│ ├ ABORh

│ ├ CodabarABORh

│ ├ CodabarABORhLongDate

│ ├ CodabarAutologous

│ ├ CodabarExpirDateTime

│ ├ ExpDateTime

│ ├ IntendedRec

| ├ PortSetupMenus

│ ├ ProdEdit

│ ├ SpecialTestDS12

│ ├ SpecialTestDS14

│ ├ UsersGuide

│ └ WalletIDCard

└ Images

Table 3: HemaTrax Client data directory tree

HemaTrax Print Server

This section deals with feature changes and additions.

Server Mode

With the introduction of the Unity releases the HemaTrax Print Server service application now operates in

one of three modes. The mode of operation is established at installation time. The mode is one of the

following given in the table below:

Server

Mode Description of Server Functionality

Master

This server accepts requests from other systems on the network to perform

maintenance on files and tables or to print labels at attached serial and

networked printers. Other systems include LIS and HemaTrax Client

applications.

Slave

(Local)

This server is installed at a workstation with the HemaTrax Client application

and is intended to provide emergency support of labeling activity to the

HemaTrax Client application running at the workstation when a master

server is unavailable. It synchronizes its data files with the master server's

files via the HemaTrax Client application. A Slave (or Local) server, will

NOT accept messages from other systems. Local files and tables can be

added to and changed when the client is running with the local server,

however, when the local file and tables are latter synchronized with the

master server any additions or changes may be lost.

Standalone

A "Standalone" mode server is installed on a workstation that is intended to

be used with the HemaTrax Client exclusively as a Standalone application.

The Client application uses this server to maintain files and print labels. The

server files and functions are only available to the HemaTrax Client

application running on the same machine. The standalone mode server will

NOT accept messages from other systems.

Table 4: Print Server modes

Service Connection Response

As explained above the print service now operates in one of three possible modes. Depending on the

service mode and where a socket connection request is originating from the print service may respond

differently. The following paragraphs explain these differences.

Master Mode

When the print server is operating in "Master" mode, it behaves exactly as the print server has in its

previous releases. A print server in master mode will accept connections and request messages from other

systems on the network. When a socket connection is made to the print service the unsolicited message,

"HemaTrax Print Server Connected" is sent to the client application. The remote application must read

this message before attempting a dialog with the print server.

Slave Mode

A print server operating in "Slave" mode, will not accept socket connections from any system other than

the one that the service is actually running on. If a client running on another system attempts to connect to

a "slave" server the unsolicited message, "Slave/Standalone Connection Refused" is sent to the client

application and the socket connection is immediately closed. When a connection is made from the same

system that the service is running on the standard unsolicited message, "HemaTrax Print Server

Connected" is sent to the local client application.

Standalone Mode

A print server operating in "Standalone" mode, will not accept socket connections from any system other

than the one that the service is actually running on. If a client running on another system attempts to

connect to a "Standalone" server the unsolicited message, "Slave/Standalone Connection Refused" is

sent to the client application and the socket connection is immediately closed. When a connection is made

from the same system that the service is running on the standard unsolicited message, "HemaTrax Print

Server Connected" is sent to the local client application.

Changed Print Service Messages/Responses

The following paragraphs describe print service messages whose message structure have been changed

from the most current Version 3.x production releases of the print service.

Get Printer Port (GPT)

The GPT message response structure that is returned in the version 3.x releases of the print service, as it

is defined in the API Guide, is shown below:

"<Port Number>","<Port Description>","<Printer Model Code>","<Baud Rate>","<CRC

Flag>","<Form Code>"<cr>

Table 5: Version 3.x Print Service GPT message response

The new HemaTrax print service responds to the GPT message from the client with an altered response

format. The new response format is shown with the highlighted changes below:

"<Port Number>","<Port Interface>","<Port Description>","<Printer Model

Code>","<Baud Rate>","<CRC Flag>","<Form Code>"<cr>

Table 6: New Print Service GPT message response

The <Port Interface> portion of the response is the same data content as was found in <Port Description>

portion of the response from the previous 3.x releases. This field contains the interface description used to

target the printer. For example, if the printer is attached to the "COM1" serial communications port on the

system hosting the print service then this field will be "COM1". As another example, if the printer

targeted to print a label is at the IPv4 dotted IP network address "192.168.1.212", then that is what will be

in the response for the Port Interface field.

The <Port Description> field of the previous 3.x releases of the print server is redefined to have a new

meaning in the new HemaTrax print service release. Now, Port Description is exactly that; it's a generic

description field up to forty characters in length that may be used for any purpose by the end user.

Note: The file migration utility used to convert and transfer files and tables from

previously installed Version 3.x releases prior to the first Unity release will handle

transferring the appropriate information to these fields and will create an initial Port

Description consisting of the printer manufacturer name and the interface description.

Set Port (SPT)

The SPT message structure that was transmitted to the print server in version 3.x releases is shown below:

SPT,"<Port Number>","<Port Description>","<Printer Model Code>","<Baud Rate>","<CRC

Flag>","<Form Code>"<cr>

Table 7: Version 3.x Print Service SPT message

The new HemaTrax SPT message transmitted to add or change printer port settings is shown with the

highlighted changes below:

SPT,"<Port Number>","<Port Interface>","<Port Description>","<Printer Model

Code>","<Baud Rate>","<CRC Flag>","<Form Code>"<cr>

Table 8: New Print Service SPT message

The <Port Number> allowed range has been expanded from 1 to 32 port definitions to the range 1 to 64.

The <Port Interface> portion of the response is the same data content as was found in <Port Description>

portion of the response from the previous 3.x releases. This field defines the interface used to target the

printer. For example, if the printer is attached to the "COM1" serial communications port on the system

hosting the print service then this field will be "COM1". As another example, if the printer targeted to

print a label is at the IPv4 dotted IP network address "192.168.1.212", then that is what will be in the

entry for the Port Interface field.

The <Port Description> field of the previous 3.x releases, prior to the first release of Unity, of the print

server is redefined to have a new meaning in the new HemaTrax print service release. Now, Port

Description is exactly that; it's a generic description field up to forty characters in length that may be used

for any purpose by the end user.

Version (VER)

The server response to the VER message has been altered. The response to the VER message in the

previous Version 3.x releases is shown below:

HemaTraxSrvr: Ver 08343.0941

HTLibDLL: Ver 08343.0911

IsamDLL: Ver 08343.0911

PCode.tbl Released: 05/20/2008

Cur Dir: C:\Program Files\HemaTrax Print Server\

Table 9: Print Service response to VER message in previous Version 3.x releases

The new VER message response is shown below with the additional or altered information highlighted:

HemaTraxSrvr: Build 13311.1338 [Master]

HTLibDLL: Build 12157.1000

IsamDLL: Build 10062.1122

PCode.tbl Released: 8/10/2011 10:26:16 AM

Home Dir: C:\ProgramData\HemaTrax_Print_Server\

Table 10: Response to VER message in the new print service release

Server Mode

At the end of the first VER response line, with all releases beginning with the first Unity release, the word

enclosed in square brackets " [ ] " indicates the server mode. For any client sending the VER message

from a system other than the one hosting the print service, the only server mode reported will be

"[Master]". The other possible server modes reported to the local machine's Client application are

"[Slave]" and "[Standalone]".

PCode.tbl Release Time

The time of table creation is now reported at the end of the fourth line of the VER response from the print

server. This time is Central Time for the mid-west United States on the date provided.

Current/Home Directory

In the previous Version 3.x releases of the print server the current directory reported by the print server

application indicated the directory path where the print server application and its data files were located.

With the new print server the home data directory path is now reported. This provides an easy way to

determine the directory that should be saved (backed up) on a periodic basis.

New Print Service Messages

The following table lists print service messages that have been added beginning with the first Unity

release. These are messages that do not exist in the most current Version 3.x production releases of the

print service.

Note: For details regarding these new messages it is important to use the new API

Guide that is supplied in the Software Development Kit (SDK) version of the

HemaTrax Print Service product. The "End Use" version is intended strictly for

installation on a production site. The SDK version is intended for use by developers to

create and test their interface to HemaTrax.

It must also be noted here that all of the new messages that print labels will eventually

replace their older counter parts of the Version 3.x releases. No specific date has been

selected yet for the removal of support for the older messages.

It is recommended that developers of the interfaces to HemaTrax Print Server

consider transitioning to the new message formats at the earliest date practical.

New

Message

Message Eventually

to be Replaced

DPR DAP

FPM GPM

GPD GPI

PAT PAD

PDL PDT

PFF OFF

PFP OFP

PPD OPD

PPR OPR

SPD SPI

Table 11: New messages to eventually replace Ver. 3.x messages

For details regarding the new messages please consult the API guide that is included as part of the

installation.

Note: The API guide is distributed as a PDF document with the Software Developers

Kit distributions only. You can only access the guide, after completing the installation

of the new software. From the Windows "Start Menu" and with "All Programs"

displayed, click on the "HemaTrax_Unity" item. From the short list of selections then

shown, choose the "HemaTrax Print Server API Guide" by clicking on it. Provided

that you have the Adobe Acrobat Reader installed on your system, the guide will

display in a moment.

HemaTrax Print Server Settings

The HemaTrax Print Server Settings application establishes various parameters used by the print server.

For details relating to the operation of this updated application please refer to the separate document that

addresses these new features and changes. What follows is a nutshell description of the enhancements.

Enhanced Security

Beginning with the first Unity release the "HemaTrax Print Server Settings" application can only be

executed by an "Administrator" on the Windows system. The application enforces Windows User

Account Control (UAC). When the Windows Administrator starts the application that person will be

required to next enter the ID and Password of the HemaTrax Print Server Administrator which was

established as part of the HemaTrax Unity installation procedure. The print server settings file,

maintained by this application, is now stored in an encrypted format to discourage tampering.

"Do not print" check boxes

Beginning with the first Unity release, three new check boxes have been added to the "Print Server

Controls" panel of the "HemaTrax Print Server Settings" application. These check boxes allow the print

server administrator to turn off the printing of: (1) Registration Number lines, (2) License Number lines

and (3) the "Rx only" line.

Alternative Properly Identify Intended Recipient and See Circular Text

Beginning with the first Unity release, the new "Alternative Properly Identify Intended Recipient and See

Circular Text" panel has been added to allow easier maintenance of the "PIIRSeeCircular.txt" text file.

This text file was formerly created manually by a text editor, such as Notepad. A check box now controls

whether or not the alternative text maintained inside the memo box is printed on FDA compliant quadrant

one labels.

Maximum Time Periods

Beginning with the first Unity release, two edit boxes on the new "Maximum Time Periods" panel allow

the operator to establish: (1) an idle time after which a client user will have to log on again and (2)

establish the number of days after which a user must define a new password. This only effects HemaTrax

Client users and does not have any impact on LIS connections.

Added ABO-Rh Codes

Beginning with the first Unity release, eight new ABO-Rh message codes have been added to the print

server's label request messages which include the ABO-Rh (quadrant two) label. The eight new codes

may be used with any print request message that includes the printing of the quadrant two (ABO-Rh)

label. The new codes are listed in the table below:

ABO-Rh

Code

ABO-Rh

Description

"17" O para-Bombay Rh Negative

"18" O para-Bombay Rh Positive

"19" A para-Bombay Rh Negative

"20" A para-Bombay Rh Positive

"21" B para-Bombay Rh Negative

"22" B para-Bombay Rh Positive

"23" AB para-Bombay Rh Negative

"24" AB para-Bombay Rh Positive

Table 12: Added para-Bombay ABO-Rh Codes

These new ABO-Rh message codes have not only been incorporated into the new message request codes,

but are also now available in the original label request messages as well.

Donation ID Number Flag Digit Rotation Changed

In releases prior to the first Unity release of the HemaTrax Print Server the flag digits, that are printed

below the DIN bar code, were rotated 90 degrees counter-clockwise. This new release corrects the

rotation so that the flag digits are now printed with a 90 degree clockwise rotation.

New Product Label Database

In the first Unity release several columns in the previous product label database have been changed to

support changes in the printing logic for the product label (quadrant three). Due to the paradigm changes

in the product label format logic in the new release, the Ver. 3.x release label message formats are not able

to be used with the new database. The original product label database is still shipped with the new

HemaTrax software. The original database and the alternate produce codes created by the user continue to

be used in the original label request messages that print any label that includes the product label (quadrant

three). The table below compares the column changes between the original database and the new

database.

Original Product Label

Table Column Names

New Product Label

Table Column Names

Description of the column change

and how product label print logic changed.

(none)

VolCode 5,6

VolPrompt 5,6

VolRngLow 5,6

VolRngHigh 5,6

Eight columns have been added to the product label

database to support the inclusion of two additional

unknown component volumes or measures.

NotUSA (none)

The ICCBBA no longer defines a table column that

indicates whether or not a product is manufactured in

the United States. This boolean column has been

eliminated in the new product label table.

MfrCaution MfrCaution

Formerly this 65 character column held static text that

was printed on the product label. Text such as

"CAUTION: FOR MANUFACTURING USE

ONLY". Now this is a 2 character columnb holding

the intended use attribute code defined in the

ICCBBBA product database. This code is now used in

conjunction with the "affirmed question code" to

indicate what, if any, dynamic manufacturing use text

is to be printed on the product label.

CollDateFlag RequiredDateCode

The CollDateFlag was a boolean flag that indicated

whether the product required a collection date (True

or False). The column has been renamed to

"RequiredDateCode" and is a single digit ASCII

numeric character that represents one of four

collection/expiration date requirement possibilities.

Table 13: Product Label Table Changes

This second release of Unity includes an expanded ICCBBA PCode table that includes blood product

codes current to November 1, 2013.

Added Unknown Volume Codes

Beginning with the first Unity release, two new unknown volume codes have been added. These two

codes provide for the inclusion of Plasma ABO-Rh and Hematocrit Percentage information on the

product label. The table below shows the new codes and their meaning:

Unknown

Volume Code

Meaning of

Unknown Volume Code

"9" Plasma ABO-Rh Text

"A" Hematocrit percent

Table 14: Added Unknown Volume Codes

Unknown Volume Value Substitution Error

In mid-October 2013 a regression error not caught during validation was detected. This impacts the first

release of the Unity print server (server Build Number: 13063.1145 Library Build Number: 13058.1036).

If the unknown volume codes and values are not provided, in the product portion of any label print

message that includes the product label quadrant, in the order that they are specified in the PCode or

AltPCode tables, then they will not be filled in the correct areas of the product label. This second release

of the Unity print server corrects that problem (Server Build Number: Library Build Number: ).

HemaTrax Client

Beginning with the first Unity release, the HemaTrax Client application is an entirely new program that

not only replaces the original HTClient.exe utility program, but now represents a production quality label

manufacturing application. The following paragraphs serve to briefly describe this new application. For a

more complete and detailed treatment of the HemaTrax Client please refer to the separate documentation

supplied for that application.

HemaTrax Client Functionality

Beginning with the first Unity release, the functionality available from the HemaTrax Client application

depends on the operating mode of the print server that is connected to. The following paragraphs

generally describe the server modes and how they impact the HemaTrax Client's functionality.

Master Server Connection

Beginning with the first Unity release, when a HemaTrax Client application connects with a print server

operating in "Master" server mode, the client application will have access to the files and operational

capabilities of the remote or local master server. The client application will be sharing the resources of

that master server with any other clients distributed on the network. This is a multiple user operating

environment. Any restrictions on what a user may do are the result of any security limitations that might

be placed on the user.

Slave Server Connection

Beginning with the first Unity release, when the HemaTrax Client program connects with the local slave

print server, the client application will be able to generally operate as when it connects with a master

server. The exception is that any local file or table modifications made while connected to the slave

server, may be lost once a connection is re-established with the remote master server and the databases

are then resynchronized. Slave server mode operation is intended for use during emergencies when the

master server may not be available. Client or LIS applications cannot connect with a slave server running

on another machine.

Standalone Server Connection

Beginning with the first Unity release, when a HemaTrax Client program connects with a local print

server operating in "Standalone" server mode, the client application will have maintenance access to the

files on the local standalone server. The client application will be able to perform maintenance on all file

and tables and have full label printing capabilities at the local machine's serial ports or at any network

printers. This is a full single user operating environment. Restrictions on what a user may do are the result

of application or network security limitations placed on the user. Client or LIS applications running on

other machines cannot connect with a standalone server.

File Migration Utility

The file migration utility is a program that is called from the installation wizard near the end of the

installation process. The file migration program searches all of the Windows directories for matches on

files known to exist in either a current or previous HemaTrax Standalone installation or a previous pre-

Unity Print Server installation. The file migration utility builds a list of all directories that have these files

contained in them. After the migration utility completes its scan the utility may ask the operator for a

confirmation that a file migration from a previous or current Standalone or a previous pre-Unity Print

Server installation is to be performed. If the operator acknowledges that a standalone or print server

migration is to be performed and if there is more than one possible directory with remaining files, the

operator will be prompted to select which directory is to be used as the source for the migration.

Important Note: If you are installing from a previous release of Unity then DO NOT perform any file

migration as this would possibly regress data file changes that you have made since the first copy of the

Unity release was installed.

New Directory Tree Structure

Beginning with the first Unity release, the new HemaTrax software makes use of a directory tree structure

that differs from the previous pre-Unity releases of the software installation. The migration utility in

cooperation with the installation wizard makes certain that the directories and sub-directories are properly

created in advance of the file conversions and copy operations.

Conversions of Files

Some files and tables have altered record structures in the new software. These files and tables from a

previous installation undergo a conversion process in order to make their content compatible with the new

software. The file migration utility handles all of these conversions.

File Copies

Some files and tables do not require any conversions, but do need to be copied to the various directories

or sub-directories used by the new software application. All necessary file copy operations are handled by

the migration utility.

Migration Utility Restriction

The migration utility has been written to only execute from within the installation process. While the

migration utility program can be found in the Program Files directory after installation, it isn't possible to

run it either accidentally or intentionally outside of the installation process.

Note: For detailed information about the file migration utility it is recommended that

users consult the PDF file, "UnityFileMigration.pdf", located in the root directory of

the installation CD-ROM.