$TXT Created by MENDOZA,RAUL at PAT-XWB.FO-OAKLAND.MED.VA.GOV (KIDS) on Wednesday, 06/08/05 at 14:11 ============================================================================= Run Date: OCT 26, 2005 Designation: XWB*1.1*34 Package : XWB - RPC BROKER Priority: Mandatory Version : 1.1 SEQ #33 Status: Released Compliance Date: NOV 26, 2005 ============================================================================= Subject: M2M Bug Fixes Category: - Routine Description: ============ Patch XWB*1.1*34 addresses (fixes) the following issues with the M-to-M Broker reported by the Imaging Team. 1. Control characters Data returned from RPC calls no longer contains carriage-return characters. 2. A-synchronous Disconnects ^XWBM2MC intermittently calls $$CLOSE^XWBRL after the API has already closed the socket-device. This only seems to happens if the network partner closes the socket before the process closes it. 3. Remaining information in ^TMP $$CLOSE() did not KILL the entry in the ^TMP global for the current context, in which it was written originally to do so. 4. Error Reporting When an error occurs inside an RPC on the remote machine, the M2M broker client has no documented mechanism to report back any information about the error tot he client. 5. Imbalanced Quote Characters in XML Message When the M2M broker server attempts to report a M (MUMPS) error back to the client, it generates incorrect XML code containing imbalanced quote characters causing the client to receive no response at all. 6. Embedded Control Characters in XML Message When the M2M broker server attempts to report an M error back to the client, it generates incorrect XML code containing embedded "<" and ">" characters. These characters are confusing the VistA XML parser causing the client to receive no response at all. 7. Undefined Variable (XWBOS) The server-side code intermittently encounters an undefined variable XWBOS error. Because the error causes the server never to send a response to the client, the client receives a "Socket Broker" error message. 8. Multi-divisional Sites and $$CONNECT The $$CONNECT() function does not work for multi-divisional sites because it only established unsubscripted DUZ. This API has been updated to establish subscripted DUZs (e.g., DUZ(1),DUZ(2), etc. ) resolving this issue. 9. Documentation of Return Values The documentation of the M2M client is in conflict with the actual implementation with respect to consolidated sites: The documentation in routine XWBM2MC states: ; Return (1)=DUZ, (2)=(0=OK, 1,2...=Can't sign-on for some reason) ; (3)=verify needs changing, (4)=Message, (5)=0, (6)=msg cnt, (6+n) ; ((6)+7)=# div user must select from, ((6)+7+n)=div thus suggesting that a list of possible locations is returned by the login-request. In reality an explicit RPC must be called to obtain the list of possible locations (or "divisions"). There is no documentation that indicates what the name of that RPC is, or how it ought to be called. 10. RPCs with no Input Parameters When an RPC is called that has no input parameters, an error occurs, which is not at all reported to the calling software. 11. Port Number is Hard Coded in Menu Option XWB M2M CACHE LISTNER The port-number for the M-to-M Broker listener is hard-coded in the menu option named XWB M2M CACHE LISTNER, which starts the listener. Because the port number is not passed as a site-parameter, this makes it impossible to run multiple VISTA systems on one machine, each with its its own port-number. This makes testing difficult. 12. Menu option XWB M2M CACHE LISTNER uses wrong commands to start listener The menu option named XWB M2M CACHE LISTENER, which is used to start the listener for the M-to-M broker, issues a M "DO" command, rather than a M "JOB" command. As a result, when the menu option XWB M2M CACHE LISTENER is started, the incorrect use of the M "DO" command never returns to the menu program. 13. Distinction between "Logins Disabled" and "Invalid Access Information" The function $$CONNECT^XWBM2MC returns a value of "0" when no connection can be established, without providing any additional information as to why the connection failed. Possible causes are: -Could not open the
and port connections (most likely because server process is not currently running) -XUS SIGNON SETUP RPC failed -XUS AV CODE RPC failed -Invalid user, no user number returned (most likely because specified Access or Verify code is not valid) -Could not obtain list of valid divisions for current user -User Set-Up in VistA does not reflect access to DICOM Gateway -Could not Set active Division for current user 14. Special characters in returned values. When a parameter is passed to an RPC and that contains special characters like <, >, & or ", the API on the client "escapes" them and the code on the server resolves the escaped values to the original characters before the RPC code is called. However, when a value that is being returned contains one of the special characters, it is passed "unedited", and has the potential of confusing the parser on the receiving end. 15. Unlock in Error Trap When an error occurs inside an RPC, the default situation is as follows: - Broker traps the error - logs it using ^%ZTER - returns error information to the client - waits for the next RPC call. Optionally, the code inside the RPC function can establish its own error trap. The "default" error trap does not release any LOCKs that may have been established inside the RPC. 16. Change in Meaning of $X between Cach 4.x and Cach 5.x There is a slight but nasty difference between Cache 4.x and Cache 5.x that relates to the meaning of $X in TCP/IP I/O. Patch XWB*1.1*34 introduces two new M-to-M Broker APIs, a modified option, and provides a new entry point to create a TCP/IP service, described as follows: ================================================================= NEW M-TO-M BROKER APIs 1. $$GETDIV^XWBM2MC() - this API gets the division/s for a user. Returns 1-success, 0-fail. This API require on parameter where the division string will be placed. Format: $$GETDIV^XWBM2MC(XWBDIVG) XWBDIVG - where the division string will be place. Results: XWBDIVG(1) - number of divisions XWBDIVG(#) - "ien;station name;startion #" 2. $$SETDIV^XWBM2MC() - set the division for a user. Returns 1-success, 0-fail. Requires a parameter which is the division to set. Format: $$SETDIV^XWBM2MC(XWBDIVS) XWBDIVS - is the division to set. Use the ien from $$GETDIV() MODIFIED OPTION 1. XWB M2M CACHE LISTENER - port number is no longer hard coded. This option will prompt the user to enter a port number (4800 is the default). The option will "job" off the task to start the listener. (**It is recommended to use the TCP/IP Service**) For example: XWB M2M CACHE LISTENER Start M2M RPC Broker Cache Listener PORT: 4800// NEW ENTRY POINT 1. STRT(PORT) - This entry is called from the option "XWB M2M CACHE LISTENER " and "job" off the listener for Cache sites. Cache/VMS sites have the option to create a TCP/IP services and use the entry point CACHEVMS^XWBVLL described in patch XWB*1.1*41. Patch Tracking #: 41152162 =========================== List of Test Sites ================== VISTA Imaging System Team, Washington Office of Information Field Office (OIFO) Atlanta VAMC Biloxi VAMC Fayetteville NC VAMC Little Rock VAMC Prescott VAMC Seattle VAMC Blood Bank Team Coordination ============================ Clearance - 4/13/04 Documentation ============= Vista M-to-M Broker, Patch XWB*1.1*34 documentation can be found in the VistA Anonymous directories and on the VistA Documentation Library (VDL) in the following two formats: XWB1_1P34SP.PDF XWB1_1P34SP.DOC The preferred retrieval method to download the documentation for Patch XWB*1.1*34 is to FTP from the ANONYMOUS.SOFTWARE directory at: DOWNLOAD.VISTA.MED.VA.GOV. This transmits the file from the first available FTP server. Sites may also elect to retrieve software directly from one of the following servers. OI Field Office FTP Address Directory ------------------------------------------------------------------ Albany ftp.fo-albany.med.va.gov ANONYMOUS.SOFTWARE Hines ftp.fo-hines.med.va.gov ANONYMOUS.SOFTWARE Salt Lake City ftp.fo-slc.med.va.gov ANONYMOUS.SOFTWARE Note: These files must be transferred in binary or IMAGE, not ASCII, mode. The VistA Documentation Library (VDL) contains all end-user manuals. Vista M-to-M Broker, Patch XWB*1.1*34 documentation is also made available online in Adobe Acrobat Portable Document (PDF) Format on the VistA Documentation Library (VDL) at the following Web address: http://vaww.vista.med.va.gov/vdl/Infrastructure.asp#App128 Routine Summary =============== The following routines are included in this patch. The second line of each of these routines now looks like: ;;1.1;RPC BROKER;**[Patch List]**;Mar 28, 1997 Checksums ========= Sites should use CHECK^XTSUMBLD to verify checksums Routine Name Before Patch After Patch Patch List ============ ============ =========== ========== XWBM2MC 6758340 9476748 28,34 XWBRL 3848552 4387751 28,34 XWBRPC 10961081 11723540 28,34 XWBRPCC 5907709 6219879 28,34 XWBUTL 3238078 3649080 28,34 XWBVLL 3252550 3398737 28,41,34 Installation Instructions ========================= >>>Users may remain on the system. >>>TaskMan does *not* need to be stopped. >>>All open connection to the M2M service should be closed. >>>It is recommended to disable the TCPIP service that is used the M2M software. 1. Use the 'INSTALL/CHECK MESSAGE' option on the PackMan menu. This option will load the KIDS package onto your system. 2. The patch has now been loaded into a Transport global on your system. Now you need 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 3. Users can remain on the system. This patch can be loaded any non-peak time. TaskMan can remain running. 4. Installation will take less than 2 minutes. On the KIDS menu, under the 'Installation' menu, use the following option: Install Package(s) 'XWB*1.1*34' ========== Want KIDS to Rebuild Menu Trees Upon Completion of Install? YES//NO == Want KIDS to INHIBIT LOGONs during the install? YES// NO == Want to DISABLE Scheduled Options, Menu Options, and Protocols? NO == 5. Enable the TCPIP service that is used by the M2M software. Routine Information: ==================== Routine Name: XWBM2MC Routine Name: XWBRL Routine Name: XWBRPC Routine Name: XWBRPCC Routine Name: XWBUTL Routine Name: XWBVLL ============================================================================= User Information: Entered By : MENDOZA,RAUL E. Date Entered : DEC 17, 2002 Completed By: SINGH,GURBIR Date Completed: SEP 23, 2005 Released By : PALMER,MICHAEL Date Released : OCT 26, 2005 ============================================================================= Packman Mail Message: ===================== $END TXT