Server Side Changes in version 1.7

This document describes the server side changes made to the Scheduling GUI to remove mumps transactions. The Scheduling GUI code was changed too in v1.7, mostly to support BMX v4. There is a single bug fix on the GUI side where support for unlinked clinics was broken inadvertently in v1.6.

Funding

Electronic Health Solutions funded this work.

Introduction and Statement of Problem

There are three issues:

1. The interaction between transactions and locking causes a freeze in GT.M that looks like this:

   GTM[******]: %%GTM-W-MUTEXLCKALERT, Mutual Exclusion subsystem ALERT - 
   lock attempt threshold crossed for region /var/worldvista/globals/mumps.dat.  
   Process 17141 is in crit. -- generated from 0x00002B158FF975CD.
   

The Scheduling GUI did a lock itself outside of the transaction in BSDX07, and Fileman did a bunch of locks internally inside the transaction.

2. Cache users will fail with an UNIMPLEMENTED error if we use the full transaction syntax which is required on GT.M.

3. Long running transactions present a problem to VISTA because unfiled transaction data can overwrite data not done via a transaction which is filed immediately. For example, in a transaction, Fileman creates records using the next available record number and files the data there. If two transactions do that at the same time that are not synchronized, we can overwrite the record; also, code outside of transactions will write the record first.

Due to all of these reasons, I decided to completely remove Mumps Transactions from the Scheduling GUI code.

Summary of Work

6 routines had to be changed: BSDX07, BSDX08, BSDX25, BSDX26, BSDX29, BSDX31. The general approach is as follows: First, we check against PIMS if applicable if we can store the data in PIMS. If we can, we go ahead and

1. File the data in BSDX APPOINTMENT, and then
2. in PIMS, and then
3. run the Appointment Event driver (SDAM APPOINTMENT EVENTS in the Protocol File). This last step is the point of no return.

If we fail in 1, we don't need to roll back anything. If we fail in 2, we need to rollback 1. If we fail in 3, we really don't have any recourse. For practical reasons, I decided that I will handle errors that can be reported to me (e.g. Fileman failing to store data). Mumps level errors I cannot handle gracefully; however, I put code to try to recover in certain places where I thought it would be practical to do so.

Individual Routines

BSDX07 (Make appointment)

Workflow:

• Lock node by patient ID
• Check if appointment can be stored in PIMS if applicable (i.e. if this is a linked resource)
• File data into ^BSDXAPPT - on failure, nothing to rollback
• File word processing field - no error checking is done here (easy to detect by end users if they lose data)
• If applicable, uncancel existing appointment in file 2 (rollback: delete everything)
• OR Add a new appointment to file 2 (rollback: delete everything)
• Add the appointment time to file 44 appointment subfile (rollback: delete everything)
• Add the patient to the file 44 patient subsubfile under the appointment subfile. (rollback: delete everything)
• Update availablities (global sets only)
• Call event driver

Rollback strategy: Difficult because of all the different possible failure points. Delete all appointments from all files.

M Error handling: Delete all appointments where possible.

Limitations of Rollback: If the patient has a previous canceled appointment in 2 at the same time and an error happens in storing the new appointments, the old appointment is deleted. From $$UNMAKE^BSDXAPI:

    ; TODO: If Patient Appointment previously existed as cancelled, it's removed.
    ; How can I tell if one previously existed when data is in an intermediate  
    ; State? Can I restore it if the other file failed? Restoration can cause   
    ; another error. If I restore the global, there will be cross-references    
    ; missing (ASDCN specifically).                                             

BSDX08 (Cancel appointment)

Workflow:

• Lock appointment
• Check if appointment can be cancelled in PIMS
• Add cancellation data in BSDX APPOINTMENT (rollback: none needed on failure)
• Cancel appointment in 2 (rollback: remove cancellation data)
• Delete appointment in 44 (no error detection as Fileman is not expected to fail)
• Update availabilities (Global sets only)
• Call event driver (point of no return)

Rollback strategy: it's easier than BSDX07 because there is only one point at which we can fail after we put data into the system. Rollback removes cancellation data from ^BSDXAPPT.

M Error Handling: Same as rollback.

Limitations of Rollback: If an M error occurs in the event driver, I do not uncancel in file 2 and restore the entry in file 44.

BSDX25 (Check-in and Remove Check-in)

Workflow for Check-in:

• Lock appointment
• Check if we can check-in the appointment in PIMS
• Check-in the appointment in BSDX APPOINTMENT (rollback: none needed on failure)
• Add check-in in file 44 (rollback: remove check-in in BSDX APPOINTMENT)
• Call event driver (point of no return)

Rollback strategy: Single point of failure: reverse check-in at BSDX APPOINTMENT.

M Error Handling: none. If the error occurs inside BSDXAPI, the same rollback activates and rolls back check-in in BSDX APPOINTMENT.

Limitations of Rollback: If an M error occurs in BSDX25 after BSDX APPOINTMENT filing, it is not rolled back.

Workflow for Remove Check-in:

• Lock appointment
• Check if check-in can be removed in PIMS
• Get old check-in date and save off in case of rollback.
• Remove check-in from BSDX APPOINTMENT (rollback: none needed on failure)
• Remove check-in from 44 (rollback: put check-in back into BSDX APPOINTMENT)
• Call event driver (point of no return)

Rollback strategy: Single point of failure: reverse check-in at BSDX APPOINTMENT.

M Error Handling: none. If the error occurs inside BSDXAPI, the same rollback activates and puts back the check-in in BSDX APPOINTMENT.

BSDX26 (Update Note on Appointment)

Workflow:

• Lock appointment
• Save ^BSDXAPPT(BSDXAPTID) into ^TMP($J)
• Change note in BSDX APPOINTMENT (rollback: none needed on failure)
• Update the note in PIMS (rollback: restore ^BSDXAPPT(BSDXAPTID) from ^TMP($J))

Rollback strategy: Restore from ^TMP.

M Error Handling: none, except as a side effect of failure from BSDXAPI, while will trigger the PIMS failure rollback.

BSDX29 (Copying appointments from PIMS to BSDX APPOINTMENT)

Transaction processing was removed from this routine; it shouldn't have been there in the first place. A lock is made for before each data filing set for job coordination.

BSDX31 (No-show and Undo No-show)

Workflow:

• Lock appointment
• Ask PIMS if it is okay to (un)no-show this patient. (Doesn't do anything currently; see TODO below)
• (un)No-show in BSDX APPOINTMENT (rollback: none needed on failure)
• (un)No-show in File 2 (rollback: reverse no-show)
• Run event driver

Rollback strategy: Reverse No-show, which is a boolean variable in ^BSDXTMP.

M Error Handling: none, except as a side effect of failure from BSDXAPI, while will trigger the PIMS failure rollback.

Unit Test Routines

As part of the changes, comprehensive Unit Test routines were created. They are BSDXUT, BSDXUT1, and BSDXUT2. They assume the existence of patients with DFNs 1 through 5. They handle setting up the Scheduling GUI and Hospital Location files themselves. The Unit Tests are:

• UT07^BSDXUT for Unit Testing BSDX07.
• UT08^BSDXUT1 for Unit Testing BSDX08.
• UT26^BSDXUT1 for Unit Testing BSDX26.
• UT29^BSDXUT1 for Unit Testing BSDX29.
• UT31^BSDXUT1 for Unit Testing BSDX31.
• UT25^BSDXUT2 for Unit Testing BSDX25.
• PIMS^BSDXUT2 for Unit Testing PIMS APIs in BSDXAPI.

All Unit Tests will try to be as silent as possible. If there is an error, it will be printed to the screen.

All tests in each Unit Test routine can be invoked from the top of each routine. To run all unit tests, execute the following. The expected output will be as follows:

GTM>D ^BSDXUT,^BSDXUT1,^BSDXUT2
Error in -10 in Unlinked Section (existing bug)
Waiting for 5 seconds for taskman to finish
Waiting for 5 seconds for taskman to finish

Other Enhancements

• As stated above, there is a fix in the Scheduling GUI C# code in v1.7 to prevent crashing if an unlinked clinic (unlinked to PIMS that is) exists. This bug was introduced in v1.6.
• No-show now calls the PIMS event driver.
• Cancel and Remove check-in check for check-out data on the PIMS appointment.
• Appointment and Routing slips were changed to include EHS's changes.
• KIDS build doesn't include BMX remote procedures in the BSDX context anymore as BMX 4 handles context switching internally.

TODO

• No-show check doesn't do anything right now. It needs more coding and comparison with PIMS.
• PIMS lets you cancel appointments without removing the check-in (different behavior in VISTA than in RPMS!). Right now, the Scheduling GUI emulates RPMS behavior.