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.

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 appointment in 2 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)

• 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 file into BSDX APPOINTMENT for coordination.

Unit Test Routines

Other Enhancements

TODO