VAPALS-ELCAP: SAMI 18-14-16-t1

$TXT by YAW,LINDA linda.yaw@vistaexpertise.net (KIDS) 2021-09-24t18:17z

Philadelphia Data Import

SAMI (VAPALS-ELCAP) 18-14-16-t1

(SAMI*18.0*16 SEQ #14 T1)

George P. Lilly, Domenic DiNatale, Larry G. Carlson & Frederick D. S. Marshall
2021-09-24

‍i. Front matter

App

SAMI (VAPALS-ELCAP)

Version

18-14-16-t1

Vista ID

SAMI*18.0*16 SEQ #14 T1: Version 18.0, Patch ID #16, Seq #14, Test 1

Priority

High

1. Description

SAMI 18-14-16-t1 adds one update, a data-import method for the Philadelphia VAPALS rollout.

The definitive source for the VAPALS-ELCAP application—codebase, package distributions (including this patch), and documentation—is a public GitHub repository.

These instructions are for your Vista environment’s sysadmin. As usual, please capture the complete dialog of your install and send it to your VAPALS-ELCAP support team.

The following list shows changes for:

High-priority changes (1)

1.1. Data Import: Add data-import functionality for the Philadelphia RedCap system

Issue 21-178: Philadelphia VA will be starting to use the VAPALS-ELCAP system soon. They want to move whatever data they can from their current LCS program which is on a RedCap database.

Solution: Develop new routine to perform import.

Reported: by the Philadelphia team.

2. Package elements

File	Change
sami-18-14-16-t1-recipe.txt	new
sami-18-14-16-t1.txt	new
sami-18-14-16-t1.kid	new
LCSV2_DATA_2021-06-29_REDCAP.tsv	new
sami-18-14-16-t1.zip	new

File

Change

sami-18-14-16-t1-recipe.txt

new

sami-18-14-16-t1.txt

new

sami-18-14-16-t1.kid

new

LCSV2_DATA_2021-06-29_REDCAP.tsv

new

sami-18-14-16-t1.zip

new

Routine	Change
SAMIHOM4	modified
SAMIHUL	modified
SAMIZPH1	new

Routine

Change

SAMIHOM4

modified

SAMIHUL

modified

SAMIZPH1

new

3. Prepare for installation

This involves creating a directory to work in, going through steps to activate the Philadelphia site, and then back up M routines that will be replaced by the patch.

3.1. Assume the identity of your osehra Unix user

This step assumes you use a dzdo or sudo command to do this; here, the symbol $DEMAND will stand for whichever command you use. (Also, in all the command-line examples below, $ simply means your command-line prompt.) If your configuration is different, please adjust this step to match your configuration:

$ $DEMAND su - osehra
$ _

3.2. Prepare install directory

If this is your first time installling this, execute the following commands. They create a shell variable, and then creates the work directory and sets it as your current directory.

$ INDIR=~/run/in/sami/18-x-16/t1
$ mkdir -p $INDIR
$ cd $INDIR
$ _

If you’ve already tried installing this once, you can use the following commands instead:

$ INDIR=~/run/in/sami/18-x-16/t1
$ cd $INDIR
$ rm -rf ./sami*.{txt,kid}
$ _

3.3. Download and prepare the archive file

You may safely download the archive file (sami-18-14-16-t1.zip) in advance of the actual install. In the following text, [now] represents a time stamp representing your current time, and [bits/sec] is a data rate and [time] is how long the file took to transfer (both of which vary based on the user’s network conditions).

$ wget --no-verbose 'http://vistaexpertise.net/newsite/project/vapals-elcap/dist/18-14-16/t1/sami-18-14-16-t1.zip'
{now} URL:http://vistaexpertise.net/newsite/project/vapals-elcap/dist/18-14-16/t1/sami-18-14-16-t1.zip [{size}/{size}] -> "sami-18-14-16-t1.zip" [1]
$ _

Then unzip the archive file with the following command.

$ unzip sami-18-14-16-t1.zip
Archive:  sami-18-14-16-t1.zip
  [... 4 files in archive ...]
$ _

3.4. Copy test-import data

This update comes with a new data-import feature to support certain sites that are using a RedCap database for their existing lung-cancer screening program. It is most convenient if this data exists in the ~/www directory.

$ cp LCSV2_DATA_2021-06-29_REDCAP.tsv ~/www/

3.5. Back up M routines

Before the installation, we also need to back up existing VAPALS-ELCAP routines that will be overwritten by this install. To do this, you will have to start a Caché or YottaDB session (depending on your particular installation), sign in to Vista, and then call the direct-mode interface ^%RO (“routine out”).

We have made efforts to display accurate instructions, but there are likely to be minor differences between implementations. Be sure to follow the correct dialog for your implementation.

3.5.1. Enter M

At the Unix prompt, enter the M environment in direct mode, using the csession command on Caché or the mumps command on YottaDB/GT.M:

On Caché

$ csession vapals

Node: vapalscache, Instance: VAPALS

>_

On YottaDB/GT.M

$ mumps -dir

>_

At the M prompt, call Vista’s direct-mode interface, enter your access code, and then just press return at the OPTION NAME prompt to return to direct mode. This sets up your authentication variables. Here’s a sample capture of this step:

>do ^XUP

Setting up programmer environment
This is a TEST account.

Access Code: *******
Terminal Type set to: C-VT100

Select OPTION NAME:
>_

3.5.3. Make Philadelphia site active

This technically doesn’t have anything to do with the routine backup, but it’s the most convenient place to take care of this.

When you log into VAPALS-ELCAP as a superuser, you are presented with a site-selection screen. If PHILADELPHA, PA VAMC - PHI isn’t on the list, then you’ll need to make that site active for this patch to work properly. Here’s how to do that:

>set DUZ=1 do ^XUP

Setting up programmer environment
This is a TEST account.

Terminal Type set to: C-VT220

Select OPTION NAME:
VAPALS YottaDB> do Q^DI


VA FileMan 22.2


Select OPTION: ENTER OR EDIT FILE ENTRIES



Input to what File: ROUTINE// SAMI SITE    (12 entries)
EDIT WHICH FIELD: ALL//


Select SAMI SITE: PHILADELPHIA, PA VAMC    PA  VAMC  642
         ...OK? Yes//   (Yes)
         PHI
SITE: PHILADELPHIA, PA VAMC//
SYMBOL: PHI//
ACTIVE: NO// YES  YES
DEFAULT PARAMETERS:
Select PARM:


Select SAMI SITE: ^




Select OPTION: ^

3.5.4. List of routines

The routine names to save are listed below; you may copy the list and paste it at the appropriate Routine prompt. At the final Routine prompt, press return to indicate the list of routines is done.

SAMIHOM4
SAMIHUL

3.5.5. Run the backup

Creating the routine backup file differs by implementation.

On Caché

Note that routines that don’t currently exist will result in a warning message (specifically, the routine name will have [???] after it, and the line [does not exist] after that). These messages can be safely disregarded.

In addition to naming the routines and routine-out file, we also provide a Description and press return at the Parameters and Printer Format prompts to accept the defaults of WNS and No, respectively:

>do ^%RO

Routine output (please use %ROMF for object code output)
Routines(s): SAMIHOM4
Routines(s): SAMIHUL
Routines(s):

Description: SAMI*18*16 SEQ #14 T1 routine backup

Output routines to
Device: /home/osehra/run/in/sami/18-14-16-t1/sami-18-14-16-t1-back.ro
Parameters? ("WNS") =>
Printer Format? No => No
SAMIOM4.INT    SAMIHUL.INT
>_

On YottaDB/GT.M

Note that routines that don’t currently exist will result in the routine name not appearing under the input line, and won’t count towards the number of routines. These can be safely disregarded.

In addition to naming the routines and routine-out file, we also provide a Header Label and press return at the Strip comments prompt to accept the default of no:

>do ^%RO

Routine Output - Save selected routines into RO file.

Routines: SAMIHOM4
SAMIHOM4
Current total of 1 routines.

Routines: SAMIHUL
SAMIHUL
Current total of 2 routines.

Routine:

Output device <terminal>: /home/osehra/run/in/sami/18-14-16-t1/sami-18-14-16-t1-back.ro

Header Label: SAMI*18*16 SEQ #14 T1 routine backup
Strip comments <No>?:
SAMIHOM4  SAMIHUL

Total of 1347 lines in 2 routines.

>_

You’ll remain in the M environment for the next section.

4. Main install instructions

This consists of loading, verifying and installing the KIDS package, and importing some test data for the new import feature.

4.1. Installing the KIDS package

This installs the various M assets required by the application.

At the OPTION NAME prompt select XPD MAIN to enter the Kernel Installation & Distribution System main menu, and at the Select ... Option prompt select Installation:

>do ^XUP

Select OPTION NAME: XPD MAIN       Kernel Installation & Distribution System


      Edits and Distribution ...
      Utilities ...
      Installation ...
      Patch Monitor Main Menu ...

Select Kernel Installation & Distribution System <TEST ACCOUNT> Option: installation


   1      Load a Distribution
   2      Verify Checksums in Transport Global
   3      Print Transport Global
   4      Compare Transport Global to Current System
   5      Backup a Transport Global
   6      Install Package(s)
          Restart Install of Package(s)
          Unload a Distribution

Select Installation <TEST ACCOUNT> Option:_

4.1.2. Load KIDS package

Select option 1:

Select Installation <TEST ACCOUNT> Option: 1  Load a Distribution
Enter a Host File: /home/osehra/run/in/sami/18-x-16/t1/sami-18-14-16-t1.kid

KIDS Distribution saved on Sep 24, 2021@17:17:40
Comment: Test release SAMI*18.0*16 SEQ #14 T1

This Distribution contains Transport Globals for the following Package(s):
   SAMI*18.0*16
Distribution OK!

Want to Continue with Load? YES//
Loading Distribution...

   SAMI*18.0*16
Use INSTALL NAME: SAMI*18.0*16 to install this Distribution.



   1      Load a Distribution
   2      Verify Checksums in Transport Global
   3      Print Transport Global
   4      Compare Transport Global to Current System
   5      Backup a Transport Global
   6      Install Package(s)
          Restart Install of Package(s)
          Unload a Distribution

Select Installation <TEST ACCOUNT> Option:_

4.1.3. Verify routine checksums

As a quality-assurance measure, we encourage you to compare routine checksums with their expacted values. To do this is simple enough:

Select Installation <TEST ACCOUNT> Option: 2  Verify Checksums in Transport Global
Select INSTALL NAME: SAMI*18.0*16       Loaded from Distribution    [now]
     => Test release SAMI*18.0*16 SEQ #14 T1  ;Created on Sep 24, 2021@17:17:40

This Distribution was loaded on [now] with header of
   Test release SAMI*18.0*16 SEQ #14 T1  ;Created on Sep 24, 2021@17:17:40
   It consisted of the following Install(s):
   SAMI*18.0*16

Want each Routine Listed with Checksums: Yes//   YES
DEVICE: HOME// ;C-SCROLL  TELNET



{page header}

SAMIHOM4  Calculated  902907585
SAMIHUL   Calculated     109364
SAMIZPH1  Calculated  214547012

   3 Routines checked, 0 failed.



   1      Load a Distribution
   2      Verify Checksums in Transport Global
   3      Print Transport Global
   4      Compare Transport Global to Current System
   5      Backup a Transport Global
   6      Install Package(s)
          Restart Install of Package(s)
          Unload a Distribution

Select Installation <TEST ACCOUNT> Option:_

These will match the “Checksum after” column in the Routines section below.

4.1.4. Install KIDS package

Select option 6, enter the space bar at the INSTALL NAME prompt, and press return at the next three prompts. Note that [now] denotes the current time when you’re doing the install.

Select Installation <TEST ACCOUNT> Option: 6  Install Package(s)
Select INSTALL NAME: SAMI*18.0*16       Loaded from Distribution    [now]
     => Test release SAMI*18.0*16 SEQ #14 T1  ;Created on Sep 24, 2021@17:17:40

This Distribution was loaded on [now] with header of
   Test release SAMI*18.0*16 SEQ #14 T1  ;Created on Sep 24, 2021@17:17:40
   It consisted of the following Install(s):
   SAMI*18.0*16
Checking Install for Package SAMI*18.0*16

Install Questions for SAMI*18.0*16



Want KIDS to INHIBIT LOGONs during the install? NO//
Want to DISABLE Scheduled Options, Menu Options, and Protocols? NO//

Enter the Device you want to print the Install messages.
You can queue the install by enter a 'Q' at the device prompt.
Enter a '^' to abort the install.

DEVICE: HOME// ;C-SCROLL  TELNET


 Install Started for SAMI*18.0*16 :
               [now]

Build Distribution Date: Sep 24, 2021

 Installing Routines:....
               [now]

 Updating Routine file......

 Updating KIDS files.....

 SAMI*18.0*16 Installed.
               [now]

 No link to PACKAGE file

 NO Install Message sent


   1      Load a Distribution
   2      Verify Checksums in Transport Global
   3      Print Transport Global
   4      Compare Transport Global to Current System
   5      Backup a Transport Global
   6      Install Package(s)
          Restart Install of Package(s)
          Unload a Distribution

Select Installation <TEST ACCOUNT> Option:


          Edits and Distribution ...
          Utilities ...
          Installation ...
          Patch Monitor Main Menu ...

Select Kernel Installation & Distribution System <TEST ACCOUNT> Option:

Select Installation <TEST ACCOUNT> Option:_

>_

4.1.5. Import test data for new import feature

Once the package has been installed, the test data that we saved off earlier into ~/www must be pulled in.

>D EN^SAMIZPH1

Select SAMI SITE: PHI  PHILADELPHIA, PA VAMC     PHI  PA  VAMC  642
File Directory: /home/osehra/www///
Enter filename to load.: LCSV2_DATA_2021-06-29_REDCAP.tsv
  Replace

McDonald
sid: PHI9000006 sikey: siform-2021-09-24
Reynolds
sid: PHI9000007 sikey: siform-2021-09-24
Kelly
sid: PHI9000008 sikey: siform-2021-09-24
Reynolds
sid: PHI9000009 sikey: siform-2021-09-24
Dee
sid: PHI9000010 sikey: siform-2021-09-24
McPoyle
sid: PHI9000011 sikey: siform-2021-09-24
Snail
sid: PHI9000012 sikey: siform-2021-09-24
Mathis
sid: PHI9000013 sikey: siform-2021-09-24
Taft
sid: PHI9000014 sikey: siform-2021-09-24
Ponderosa
sid: PHI9000015 sikey: siform-2021-09-24

>halt
$ _

4.1.6. Test installation of data-import function

You may confirm that the install has worked by pulling up the import-test data that was installed with this update. To do that, you’ll have to enter VAPALS-ELCAP on the browser, select the Philadelphia site, go to Reports, pull down, and select Enrollment. You should be looking at something that looks like this:

You now have VAPALS-ELCAP 18-14-16-t1 (SAMI*18.0*16 SEQ #14 T1) installed in your M environment. The install is now complete. We recommend running tests of your VAPALS-ELCAP application to confirm the environment is operational and bug-free, before notifying users that VAPALS-ELCAP is ready for their use.

5. Optional backout instructions

Should errors or other problems result from installing this package, contact the VAPALS-ELCAP development team for package-backout instructions.

6. Routines

Lines 2 and 3 of each of these routines now look like:

 ;;18.0;SAMI;[Patch List];2020-01;[optional build #]
 ;18-x-16-t1

The checksums below are Vista Type B checksums (do CHECK1^XTSUMBLD).

Name	Checksum before	Checksum after	Patch list
SAMIHOM4	B899951012	B902907585	1,4,5,6,9,12,16
SAMIHUL	B111466	B109364	9,12,16
SAMIZPH1	—	B214547012	16

Name

Checksum before

Checksum after

Patch list

SAMIHOM4

B899951012

B902907585

**1,4,5,6,9,12,16**

SAMIHUL

B111466

B109364

**9,12,16**

SAMIZPH1

—

B214547012

**16**

7. Authors

	Dates	By
Developed	2021-09-20/23	George P. Lilly (VEN) Dominic DiNatale (PAR) Larry G. Carlson (VEN) Frederick D. S. Marshall (VEN) Kenneth W. McGlothlen (VEN) Linda M. R. Yaw (VEN)
Tested	2021-09-23	George P. Lilly (VEN) Claudia Henschke (VA-PHO) Artit Jirapatnakul (VA-PHO) Providencia Morales (VA-PHO) Kenneth W. McGlothlen (VEN) Linda M. R. Yaw (VEN)
Released	2021-09-24	Frederick D. S. Marshall (VEN) Kenneth W. McGlothlen (VEN) Linda M. R. Yaw (VEN)

Dates

Developed

2021-09-20/23

George P. Lilly (VEN)
Dominic DiNatale (PAR)
Larry G. Carlson (VEN)
Frederick D. S. Marshall (VEN)
Kenneth W. McGlothlen (VEN)
Linda M. R. Yaw (VEN)

Tested

2021-09-23

George P. Lilly (VEN)
Claudia Henschke (VA-PHO)
Artit Jirapatnakul (VA-PHO)
Providencia Morales (VA-PHO)
Kenneth W. McGlothlen (VEN)
Linda M. R. Yaw (VEN)

Released

2021-09-24

Frederick D. S. Marshall (VEN)
Kenneth W. McGlothlen (VEN)
Linda M. R. Yaw (VEN)

$END TXT