$TXT Created by MOORE,JIM at NXT.FO-OAKLAND.MED.VA.GOV (KIDS) on Monday, 08/24/09 at 11:20 ============================================================================= Run Date: JAN 13, 2010 Designation: HL*1.6*146 Package : HL - HEALTH LEVEL SEVEN Priority: Mandatory Version : 1.6 SEQ #117 Status: Released Compliance Date: FEB 13, 2010 ============================================================================= Associated patches: (v)HL*1.6*143 <<= must be installed BEFORE `HL*1.6*146' Subject: HLO DEVELOPER MANUAL AND OTHER ENHANCEMENTS Category: - Enhancement (Mandatory) - Data Dictionary - Input Template - Routine - Informational Description: ============ Patch HL*1.6*146 provides several enhancements to the Health Level Seven Optimized (HLO) software and makes several corrections. Test Sites: =========== MPI Montana HCS Upstate New York HCS (Bath) CMOP-NAT Oklahoma City Remedy: ====== none Software Enhancements: ====================== 1) The HLO Technical Manual, version HL*1.6*126, has been replaced by two new manuals, the Health Level Seven Optimized (HLO) Developers Manual, version HL*1.6*146, and the Health Level Seven Optimized (HLO) System Managers Manual, version HL*1.6*146. These documents can be downloaded from the VISTA Documentation Library (VDL) on the HL7 Web page: http://www4.va.gov/vdl/application.asp?appid=8 2) Several new application programming interfaces (APIs) for parsing and building HL7 message segments have been added. The full descriptions are contained within the Health Level Seven Optimized (HLO) Developer Manual, version HL*1.6*146. The new APIs are: SETXPN^HLOAPI4 API - It allows the developer to set the XPN data type into a segment. GETXPN^HLOPRS2 API - It allows the developer to parse the XPN data type from a segment. MOVESEG^HLOAPI API - It allows a segment built with the traditional hard-coded segment builder to be moved into an HLO message array. MSGID^HLOPRS API - This API is used to return the Message Control ID of a message. 3) The algorithm for the client process that transmits messages has been enhanced to utilize a dynamically adjusted read timeout parameter. Prior to this patch the client used a fixed read timeout parameter of 20 seconds. The timeout parameter sets the maximum time that a client will wait for a reply over a TCP connection. The fixed read timeout parameter of 20 seconds proved to be too short for some applications, so it has been replaced by a dynamic value that will automatically adjust to longer or shorter periods when needed. 4) Several new options have been added. Please refer to the Health Level Seven Optimized (HLO) Developer Manual, version HL*1.6*146, and the Health Level Seven Optimized (HLO) System Managers Manual, version HL*1.6*146, for a full description of the new options. The new options are: HLO DEVELOPER MENU [HLO DEVELOPER MENU] - This new menu contains the options that pertain to building new message applications. APPLICATION REGISTRY MENU [HLO APPLICATION REGISTRY MENU]- This menu option contains options for added and editing entries in the HLO APPLICATION REGISTRY file (#779.2). ADD/EDIT RECEIVING APPLICATION [HLO EDIT RECEIVING APPLICATION]- This option is used to add or edit an receiving application in the HLO APPLICATION REGISTRY file (#779.2). ADD/EDIT SENDING APPLICATION [HLO EDIT SENDING APPLICATION] - This option is used to add or edit an sending application in the HLO APPLICATION REGISTRY file (#779.2). INACTIVATE SENDING APPLICATION [HLO TERMINATE OUTGOING MESSAGE] - This option is used to set the INACTIVE field (#.07)in the MESSAGE TYPE ACTIONS subfile (#779.21) of the HLO APPLICATION REGISTRY file (#779.2). If the application designed its messaging to honor this flag, then this option can be used to turn on and off its messages. ADD/EDIT SUBSCRIPTIONS [HLO SUBSCRIPTION REGISTRY] - This option is used to add or edit entries in the HLO SUBSCRIPTION REGISTRY file (#779.4). 5) Two new troubleshooting tools are available, the Client Trace Tool and the Server Trace Tool. Their purpose is to assist HL7 interface developers to diagnose problems affecting the transmission of HL7 messages via HLO. These tools allow the HLO server and client to be executed in the foreground. While they execute, attempting to send and receive HL7 messages, the user is kept informed of the progress via a stream of messages that are written to the user's screen at each step. Please refer to the Health Level Seven Optimized (HLO) Developer Manual, version HL*1.6*146, for a description of these new tools and instructions for their use. 6) A new application programming interface (API) has been added. This API is a function used to obtain a count of the number of messages on the queues. The syntax of the function is S variable=$$QUECNT^HLOQUE(.array) The number of messages pending on the message queue is returned in . The passed by reference variable returns a complete list of all of the message queue counts. The array has the following structure: array("TOTAL") = Total number of messages on all queues. array("OUT") = Total number of outgoing messages. array("IN") = Total number of incoming messages. array("SEQ") = Total number of messages on sequence queues. array("IN",link_name,queue_name) = Number of messages on given link and queue. array("OUT",link_name,queue_name) = Number of messages on given link and queue. array("SEQ",queue_name) = Number of messages on given sequence queue. 7) A new application programming interface (API) has been added. This API is a function used to obtain a count of the number of messages on the outgoing queues. The syntax of the function is S variable=$$OUT^HLOQUE(.array) The total number of messages pending on the outgoing queues is returned in . The passed by reference variable is returned contains a complete list of all of the outgoing queue counts. The array has the following structure: array("OUT") = Total number of outgoing messages. array("OUT",link_name,queue_name) = Number of messages on given link and queue. 8) A new application programming interface (API) has been added. This API is a function used to obtain a count of the number of messages on the incoming queues. The syntax of the function is S variable=$$IN^HLOQUE(.array) The total number of messages pending on the incoming queues is returned in . The passed by reference variable is returned contains a complete list of all of the incoming queue counts. The array has the following structure: array("IN") = Total number of outgoing messages. array("IN",link_name,queue_name) = Number of messages on given link and queue. 9) A new application programming interface (API) has been added. This API is a function used to obtain a count of the number of messages on the sequence queues. The syntax of the function is S variable=$$SEQ^HLOQUE(.array) The total number of messages pending on the incoming queues is returned in . The passed by reference variable is returned contains a complete list of all of the sequence queue counts. The array has the following structure: array("SEQ") = Total number of sequence queue messages. array("SEQ",link_name,queue_name) = Number of messages on given link and queue. 10) A new application programming interface has been added for obtaining HL7 messages as an array of text lines. The new API is: GETMSG^HLOAPI7(IEN,MSG,FLAG) This function allows the user to toggle between HL7 and HLO messages and to return message information in a local array or a global. I '$G(FLAG) then MSG, IEN and file 778 are used for HLO messages. I $G(FLAG) then MSG, IEN and file 773 are used for HL7 messages. 11) The following data dictionary changes to the HLO Subscription Registry file (#779.4), in the RECIPIENTS subfile (#779.41): a) The field LOGICAL LINK (#.02) has been renamed MIDDLEWARE LOGICAL LINK. b) The field FACILITY LOGICAL LINK (#.021) has been added. Software Corrections: ===================== 1) Corrected an error that was encountered when attempting to delete the top message on an empty queue. 2) Corrected an error with the SHUTDOWN LINK action of the HLO SYSTEM MONITOR option. The error was that the action did not always immediately stop messages from being transmitted. 3) Removed the synonym QD from the HLO OUTBOUND DELETE and HLO SEQUENCE DELETE protocols. The QD synonym conflicted with the QUIT action in that users who entered "Q" meaning to quit that screen were instead taken to the Delete Queue action. 4) The HLO Visual Parser was failing to parse HL7 messages. This concerns the visual display only, not the actual processing of the messages. This is fixed. Installation Instructions: ========================= 1. Users are allowed to be on the system during the installation. Installation time is under 3 minutes. 2. Disable the HL7 TCPIP services for the HLO multi-listener running on all nodes in the cluster. For example, at the VMS prompt in your production account: ISC6A1> TCPIP <-- at the VMS prompt TCPIP> DISABLE SERVICE HLS5001CACHE In your test account: ISC6A1> TCPIP <-- at the VMS prompt TCPIP> DISABLE SERVICE HLS5026CACHE You could also do this from the M programmer's prompt as follows: VISTA> D ^%CLI <-- at the M programmer's prompt CLI command: TCPIP TCPIP> DISABLE SERVICE HLS5001CACHE 3. Use the STOP HLO option of the HLO SYSTEM MONITOR screen to temporarily stop the transmission of HLO messages. Wait several minutes to insure that all HLO processes have terminated. NOTE: There is a pre-install routine that will abort the installation if any HLO process is still running. If the installation is aborted, verify that HLO is stopped, and restart the installation. 4. Use the 'INSTALL/CHECK MESSAGE' option on the PackMan menu. This option will load the KIDS package onto your system. 5. This patch is now loaded into a transport global on your system. The next step is to use KIDS to install the Transport global. On the KIDS menu, under the 'Installation' menu, use the following options: Verify Checksums in Transport Global Print Transport Global Compare Transport Global to Current System Backup a Transport Global Install Package(s) When using the Install Package(s) 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? Want KIDS to INHIBIT LOGONS during the install? Want to DISABLE Scheduled Options, Menu Options, and Protocols? A pre-install routine will verify that all HLO processes have been stopped before the installation will complete. NOTE: The routine HLOP146 will be automatically deleted upon completion of the installation. 6. Enable the HL7 TCPIP services for the multi-listeners For example, in a production account at the VMS prompt: ISC6A1> TCPIP <-- at the VMS prompt TCPIP> ENABLE SERVICE HLS5001CACHE For example, in a test account: ISC6A1> TCPIP <-- at the VMS prompt TCPIP> ENABLE SERVICE HLS5026CACHE You could also do this from the M programmer's prompt as follows: VISTA> D ^%CLI <-- at the M programmer's prompt CLI command: TCPIP TCPIP> ENABLE SERVICE HLS5001CACHE 7. Use the START HLO option within the HLO SYSTEM MONITOR screen to resume transmission of HLO messages in your production account. This step is optional in test systems. 8. On production systems, verify that outgoing messages have resumed being transmitted. You can do this by monitoring the system via the HLO System Monitor for a few minutes to insure that the count of messages pending transmission is not growing. Routine Information: ==================== The second line of each of these routines now looks like: ;;1.6;HEALTH LEVEL SEVEN;**[Patch List]**;Oct 13, 1995;Build 16 The checksums below are new checksums, and can be checked with CHECK1^XTSUMBLD. Routine Name: HLOAPI Before: B95686689 After:B114629271 **126,133,138,139,146** Routine Name: HLOAPI1 Before: B49595357 After:B101211192 **126,132,134,137,146** Routine Name: HLOAPI2 Before: B70584205 After: B76422316 **126,131,133,134,137,138,146** Routine Name: HLOAPI4 Before: B21664349 After: B29813410 **131,134,146** Routine Name: HLOAPI7 Before: n/a After: B15001817 **146** Routine Name: HLOASUB Before: B20309588 After: B34615650 **126,146** Routine Name: HLOASUB1 Before: B68656659 After: B91447015 **126,134,138,146** Routine Name: HLOCLNT1 Before: B32776376 After: B33784645 **126,130,131,134,137,139,146** Routine Name: HLOCNRT Before: B12168721 After: B16134592 **126,132,134,137,146** Routine Name: HLOP146 Before: n/a After: B1485106 **146** Routine Name: HLOPROC Before: B26319281 After: B26547261 **126,134,146** Routine Name: HLOPRS Before: B28621828 After: B29241759 **118,126,133,132,134,138,146** Routine Name: HLOPRS2 Before: B25178316 After: B34053092 **131,146** Routine Name: HLOPRSR2 Before: B77395727 After: B77677817 **138,139,146** Routine Name: HLOSRVR1 Before: B86996455 After: B86429474 **126,130,131,133,134,137,138, 139,143,146** Routine Name: HLOSRVR2 Before: B5350765 After: B5350765 **131,137,138,146** Routine Name: HLOSTRAC Before: n/a After: B33783349 **146** Routine Name: HLOT Before: B3373728 After: B3437824 **126,131,139,146** Routine Name: HLOTCP Before: B61182306 After: B85513944 **126,131,134,137,138,139,146** Routine Name: HLOTLNK Before: B25754770 After: B26226165 **126,130,131,139,146** Routine Name: HLOTRACE Before: n/a After: B65294426 **146** Routine Name: HLOUSR Before: B90546721 After: B92223063 **126,130,134,137,138,139,146** Routine Name: HLOUSR6 Before: B15582735 After: B24863677 **138,146** Routine list of preceding patches: 143 ============================================================================= User Information: Entered By : MOORE,CHARLES J Date Entered : FEB 18, 2009 Completed By: BEST,LISA Date Completed: NOV 30, 2009 Released By : APOLONIO,AUGUSTO Date Released : JAN 13, 2010 ============================================================================= Packman Mail Message: ===================== $END TXT