$TXT Created by ANDREASSEN,LARRY J at NXT.KERNEL.FO-OAKLAND.MED.VA.GOV (KIDS) on Thursday, 05/08/03 at 12:58 ============================================================================= Run Date: MAY 12, 2003 Designation: HL*1.6*93 Package : HL - HEALTH LEVEL SEVEN Priority: Mandatory Version : 1.6 SEQ #86 Status: Released Compliance Date: JUN 12, 2003 ============================================================================= Subject: Dynamic Routing Enhancement Category: - Routine Description: ============ Test sites: Charleston, Clarksburg, VA North Texas Healthcare System, Hines, Indianapolis, Louisville, Memphis, Nashville, New Jersey, Providence, San Juan PR, Puget Sound, Spokane, Tucson, Washington, Wilmington NOIS: None Note: This patch requires that KIDS build HL*1.6*94 be installed. Description: ============ Patch HL*1.6*93 is the enhancements being added to the VistA HL7 software by which routing-related fields in the MSH segment can be more easily controlled than before. After the installation of Patch HL*1.6*93, immediately before the construction of the MSH segment by the VistA HL7 software, applications calling VistA HL7 to create messages have a method to examine and set the local variables used in the MSH segment's routing-related fields. Because these APIs directly control the routing-related fields, it is now practical in many circumstances to create a generic event driver protocol and subscriber protocol to populate the routing-related fields at the time of message creation. ENHANCEMENTS TO VISTA HL7 SOFTWARE EXPORTED WITH HL*1.6*93: As of patch HL*1.6*93, users of the DIRECT^HLMA and GENERATE^HLMA APIs can now control the following MSH routing-related fields: SENDING APPLICATION, SENDING FACILITY, RECEIVING APPLICATION, and RECEIVING FACILITY. Control of these fields is obtained by passing data into these APIs used to set them at the moment the MSH segment is created. The syntax for calling these APIs is shown below D [DIRECT/GENERATE]^HLMA(HLEID,HLARYTYP,HLFORMAT,.HLRESLT,HLMTIEN,.HLP) The passed by reference HLP array controls the routing-related fields in the MSH segment. There are two legal syntax forms for HLP("SUBSCRIBER"[,n]) data shown below: HLP("SUBSCRIBER")=^[SAPP]^[SFAC]^[RAPP]^[RFAC]^[Subrtn^Rtn]" HLP("SUBSCRIBER",n)=Sub101^[SAPP]^[SFAC]^[RAPP]^[RFAC]^[Subrtn^Rtn]" When [Subrtn^Rtn] is passed, both the "Subrtn" and the "Rtn" must be included. The "n" in the second entry represents a positive canonical number like 1 or 2. Immediately before the MSH segment is created, the data in these HLP("SUBSCRIBER"[,n]) entries is evaluated. If the subscriber protocol being used by DIRECT^HLMA or GENERATE^HLMA matches Sub101, as shown above, the data on that node is used to control the MSH segment. If no subscriber protocol match is found, the general entry, HLP("SUBSCRIBER"), is used. If M code exists, it evaluates the environment and can set the local variables used to create the MSH segment if appropriate. M code is always executed as the last step. Because of this, M code actions take precedence over all other changes. VARIABLES ASSIST M CODE Patch HL*1.6*93 introduces a new API named M^HLCSHDR4. It has been created for use by application developers making calls to DIRECT^HLMA and GENERATE^HLMA. This new API is a supported reference and covered under Integration Agreement #3988 on the FORUM DBA [DBA] menu. API FUNCTIONALITY Immediately before the MSH segment is constructed, application developers can invoke M code by calling the new API MSHREC^RAMSH to directly set the local variables used for the routing-related fields in the MSH segment. The four variables that can be legally changed are listed below: HLMSHSAN--New SENDING APPLICATION to be used in the MSH segment. HLMSHSFN--New SENDING FACILITY to be used in the MSH segment. HLMSHRAN--New RECEIVING APPLICATION to be used in the MSH segment. HLMSHRFN--New RECEIVING FACILITY to be used in the MSH segment. For example, to set the RECEIVING APPLICATION field in the MSH segment, M code should set the HLMSHRAN local variable. And, when M code sets the HLMSHRFN variable, that value is used in the RECEIVING FACILITY field in the MSH segment. GENERIC SUBSCRIBER PROTOCOLS With the implementation of this patch, only one subscriber protocol is required to dynamically control the routing-related fields in MSH segment. This is a "generic" subscriber protocol. When using this generic subscriber protocol, routing-related field values will automatically be placed in the MSH segment, or that value can be overridden by HLP("SUBSCRIBER"[,n]) data. NEW OPTION In order to assist developers in finding matching protocols on sending and receiving systems, Patch HL*1.6*93 introduces a new report created to list the protocol information that is used when searching for matching protocols. This new report can be printed using the Protocol Messaging Fields Report [HL PROTOCOL MSG FIELDS REPORT] menu option, also new with Patch HL*1.6*93. (This option is located in the Reports menu, under the Interface Developer Options menu.) NEW API M^HLCSHDR4 Patch HL*1.6*93 introduces a new API named M^HLCSHDR4. It was created for use by application software developers making calls to DIRECT^HLMA and GENERATE^HLMA. This new API is a supported reference and covered under Integration Agreement #3988 on the FORUM DBA [DBA] menu. DOCUMENTATION Documentation is available outlining the details of the work involved in this patch for VistA developers and VA facility Information Resources Management (IRM) personnel. This document can be obtained by using FTP from the appropriate Customer Service directories listed below. The filename for the VistA Health Level Seven (HL7) MSH Segment Control (Dynamic Routing) documentation is HL1_6p93sp.PDF. Assure that the file transfer type is set to 'Binary' before downloading the file. OI FIELD OFFICE FTP ADDRESS ====================================================== download.vista.med.va.gov Albany ftp.fo-albany.med.va.gov Hines ftp.fo-hines.med.va.gov Salt Lake City ftp.fo-slc.med.va.gov This document can also be downloaded from the VistA Documentation Library (VDL) Web page at the following address: http://www.va.gov/vdl/Infrastructure.asp?appID=8 PACKAGE REQUIREMENTS Patch HL*1.6*93 requires that both development Test and Production accounts exist in a standard VistA operating environment in order to function correctly. The accounts must contain the fully patched versions of the following software: Health Level Seven (HL7) V. 1.6 Kernel V. 8.0 Kernel Toolkit V. 7.3 RPC Broker V. 1.1 VA FileMan V. 22.0 Routine Information =================== Please install patch HL*1.6*94 prior to installing and testing patch HL*1.6*93. (Otherwise, patch HL*1.6*93 will not work.) The following routines are included in this patch. The second line of each of these routines now looks like: ;;1.6;HEALTH LEVEL SEVEN;**[Patch List]**;Oct 13, 1995 Checksum Checksum Routine Name Before Patch After Patch Patch List ============ ============ =========== ===================== HLCSHDR1 7760350 7809108 19,57,59,72,80,93 HLCSHDR3 ------- 6199342 93 HLCSHDR4 ------- 13431553 93 HLCSHDR5 ------- 5839459 93 HLCSHDR6 ------- 4266563 93 Sites should use CHECK^XTSUMBLD to verify checksums after patch installation. Installation Instructions: ========================== Note: This patch should be installed during a time of low system activity. 1. Users are allowed to be on the system during the installation. 2. Install the KIDS build onto your system as follows: - Using Mailman, read the KIDS build message. - At the 'Enter message action' prompt, enter 'INSTALL/CHECK MESSAGE' and press RETURN. - At the 'OK to continue with Load?' prompt enter 'YES' and press RETURN. - You will be asked 'Want to continue with Load?' immediately before installation begins. If you want to continue, enter 'YES' and press RETURN. If you wish to stop, enter 'NO' and press RETURN. 3. Check the integrity of the just loaded build, and compare this build to the software on your system. You will need to use the following options (which are all on the 'Installation [XPD INSTALLATION MENU]' menu option): - VERIFY CHECKSUMS IN TRANSPORT GLOBAL - this option will allow you to ensure the integrity of the routine(s) that are in the transport global using calculated checksums for every routine. If the transport global checksums are incorrect, do not continue with installation, and contact the patch developer for a new patch. If the checksums are correct, continue to the next step. - BACKUP A TRANSPORT GLOBAL - this option will create a backup message of any routines exported with the patch. It will NOT backup any other changes such as DDs or templates. - COMPARE TRANSPORT GLOBAL TO CURRENT SYSTEM - this option will allow you to view all changes that will be made when the patch is installed. It compares all components of the patch, including routines, data dictionaries, templates, etc. - PRINT TRANSPORT GLOBAL - this option will allow you to view the components of the KIDS build. If all the above steps have been done, continue to the following steps. 4. AXP/DSM SITES: Review your mapped routine set. If the routine(s) listed in the ROUTINE SUMMARY section are mapped, they should be removed from the mapped set at this time. 5. Stop all background processes (logical links and incoming and outgoing filers) using the 'Filer and Link Management Option's 'Stop All Messaging Background Processes [HL STOP ALL]' menu option. 6. Stop the link manager using the 'TCP Link Manager Start/Stop [HL START/STOP LINK MANAGER]' menu option. 7. AXP/DSM SITES ONLY: Disable all HL7 UCX Services for this installation. 8. The patch is now loaded into a transport global on your system. The next step is to use KIDS to install the Transport global. This is done using the 'Installation' menu's 'Install Package(s) [XPD INSTALL BUILD]' menu option. When using this menu option to install the patch build, you will be asked several questions. The questions, and the answers you should supply, are shown below. INSTALL NAME: Want KIDS to Rebuild Menu Trees Upon Completion of Install? YES// Want KIDS to INHIBIT LOGONS during the install? Want to DISABLE Scheduled Options, Menu Options, and Protocols? 9. Start all background processes (logical links and incoming and outgoing filers) using the Filer and Link Management Option's 'Restart/Start All Links and Filers [HL TASK RESTART]' menu option. (Note that links that do not have "autostart" enabled will need to be restarted manually.) 10. AXP/DSM SITES ONLY: If you previously disabled an HL7 UCX Service for this installation, you may enable it now. 11. AXP/DSM SITES ONLY: After the patch has been installed, rebuild your map set, if necessary. 12. Start the link manager using the 'TCP Link Manager Start/Stop [HL START/STOP LINK MANAGER]' menu option. Routine Information: ==================== Routine Name: - HLCSHDR1 Routine Checksum: Routine Name: - HLCSHDR3 Routine Checksum: Routine Name: - HLCSHDR4 Routine Checksum: Routine Name: - HLCSHDR5 Routine Checksum: Routine Name: - HLCSHDR6 Routine Checksum: ============================================================================= User Information: Entered By : ANDREASSEN,LARRY Date Entered : MAY 03, 2002 Completed By: SINGH,GURBIR Date Completed: MAY 09, 2003 Released By : GAYFIELD,LISA Date Released : MAY 12, 2003 ============================================================================= Packman Mail Message: ===================== $END TXT