Kernel APIs: OPKG^XUHUI

OPKG^XUHUI(): Monitor New Style Cross-referenced Fields

Reference Type: Supported, Category: Field Monitoring, ICR#: 3589

Description

The OPKG^XUHUI API allows other packages to task an Option or Protocol from a New Style cross-reference. This API can be used to monitor any field or fields in any file using a New Style cross-reference.

Format

     OPKG^XUHUI([xuhuiop,]xuhuinm[,xuhuia],xuhuixr)

Input Parameters

xuhuiop:	(optional) This parameter is a set of Numeric codes that tells the Unwinder to use the PROTOCOL (#101) file or the OPTION (#19) file. If this parameter is NULL, the default value is used (i.e., 101): 101 (default)—PROTOCOL (#101) file is used. 19—The OPTION (#19) file is used.
xuhuinm:	(required) This parameter is the NAME (#.01) value of the Protocol or Option that is to be launched.
xuhuia:	(optional) This parameter is a Set of Codes. If this input parameter is NULL, the default value is used (i.e., S): S (default)—The data being passed is from the SETting of the cross-reference. K—The data being passed is from the KILLing of the cross-reference.
xuhuixr:	(required) This parameter is the name of the cross-reference.

Output

See Example

Monitored Fields with a New Style cross-reference.

Example

The Hui Project needs to monitor the following fields at the top-level of the NEW PERSON (#200) file for changes in value, in the order listed:

NAME (#.01)
TERMINATION DATE (#9.2)
DOB (#5)
SSN (#9)

Create New Style Cross-references

Create a MUMPS New Style cross-reference for the fields that are to be monitored for value changes, as shown below:

Index Name: AXUHUI (#n)

Short Description: Hui Project Top File Cross-reference

      Description: This MUMPS New Style cross-reference is on non-multiple
                   fields in the NEW PERSON (#200) file that the Hui Project
                   needs to monitor for changes in value.  The following fields
                   are being monitored in the order listed: 

                          .01 (NAME) 
                           9.2 (TERMINATION DATE) 
                           5 (DOB) 
                           9 (SSN) 
                   For details on how this cross-reference processes changes,
                   see the patch description for Kernel Patch XU*8*236.
                   For more detailed information about the MUMPS New Style 
                   cross-reference, see the "VA FileMan V. 22.0 Key  
                   and Index Tutorial" at the following web address: 

            http://vista.med.va.gov/fileman/fileMan_training/online_pres/FMtut_frm.htm
            (see Lessons #5 and #6)

               Type: MUMPS

          EXECUTION: RECORD

                Use: ACTION

      Set Logic:  D OPKG^XUHUI("","XUHUI FIELD CHANGE EVENT","","AXUHUI") Q 
     Kill Logic:  Q 
     Whole Kill:  Q 
           X(1):  NAME  (200,.01)  (forwards) 
           X(2):  TERMINATION DATE  (200,9.2)  (forwards) 
           X(3):  DOB  (200,5)  (forwards) 
           X(4):  SSN  (200,9)  (forwards)

Sample Scenario

Change a monitored (cross-referenced) field value in the NEW PERSON (#200) file, as shown below:

INPUT TO WHAT FILE: NEW PERSON// <Enter> 
 EDIT WHICH FIELD: ALL// DOB  
 THEN EDIT FIELD: SSN 
 THEN EDIT FIELD: <Enter>
   
 Select NEW PERSON NAME: KRNUSER <Enter> KRNUSER,ONE     OK 
 DOB: JUL 4,1950// 12.24.49 <Enter> (DEC 24, 1949) 
 SSN: 000220000// 000558888

In this example the ONE KRNUSER's Date of Birth (DOB) was changed from 07/04/50 to 12/24/49 and also changed the Social Security Number (SSN) from 000-22-0000 to 000-55-8888. Since these fields are being monitored (i.e., MUMPS New Style cross-reference, see the "Create Cross-references" topic), you should see this data passed to the "XUHUI FIELD CHANGE EVENT" protocol (see the " Internal Results for Developers" section that follows).

Internal Results for Developer

The following data is passed to the "XUHUI FIELD CHANGE EVENT" Protocol via the Kernel OPKG^XUHUI API that is called in the AXUHUI cross-reference (see the "Create Cross-references" topic). (Comments about the data are displayed in boldface type and in italics.)

 -------------------------------------------------------------------------
 If executing the Kill logic, then the 'X' array will  be equal to the 'X1'
 array.  If executing the Set logic, then the 'X' array will be equal to
 the 'X2' array.  
 -------------------------------------------------------------------------
 X=KRNUSER,ONE 
 X(1)=KRNUSER,ONE 
 X(2)= 
 X(3)=2491224 
 X(4)=000558888 
 -------------------------------------------------------------------------
 X1=KRNUSER,ONE  <-- Old values are in this array. 
 X1(1)=KRNUSER,ONE 
 X1(2)= 
 X1(3)=2500704 
 X1(4)=999220000 
 -------------------------------------------------------------------------
 X2=KRNUSER,ONE  <-- New values are in this array. 
 X2(1)=KRNUSER,ONE 
 X2(2)= 
 X2(3)=2491224 
 X2(4)=000558888 
 -------------------------------------------------------------------------
 XUHUIA=S  <-- "S" = Set Logic is being executed, "K" = Kill logic being executed. 
 XUHUIDA=70  <-- "DA" array.
 XUHUIFIL=200  <-- File number.
 XUHUIFLD=  <-- Field numbers if available. 
 XUHUINM=XUHUI FIELD CHANGE EVENT  <-- Name of Extended Action entry in 
                                        File #101 or in File #19.
 XUHUIOP=101 <-- File number of where to find the Extended Action.
 XUHUIX=KRNUSER,ONE  <-- The "X" array. 
 XUHUIX(1)=KRNUSER,ONE 
 XUHUIX(2)= 
 XUHUIX(3)=2491224 
 XUHUIX(4)=000558888 
 XUHUIX1=KRNUSER,ONE  <-- The "X1" array. 
 XUHUIX1(1)=KRNUSER,ONE 
 XUHUIX1(2)= 
 XUHUIX1(3)=2500704 
 XUHUIX1(4)=999220000 
 XUHUIX2=KRNUSER,ONE  <-- The "X2" array. 
 XUHUIX2(1)=KRNUSER,ONE 
 XUHUIX2(2)= 
 XUHUIX2(3)=2491224 
 XUHUIX2(4)=000558888 
 XUHUIXR=AXUHUI  <-- Name of cross-reference being executed by DIK.