MAGUTL01.m

MAGUTL01 ;WOIFO/SG - PARAMETERS AND VALIDATION UTILITIES ; 3/9/09 12:53pm

 ;;3.0;IMAGING;**93**;Dec 02, 2009;Build 163

 ;; Per VHA Directive 2004-038, this routine should not be modified.

 ;; +---------------------------------------------------------------+

 ;; | Property of the US Government.                                |

 ;; | No permission to copy or redistribute this software is given. |

 ;; | Use of unreleased versions of this software requires the user |

 ;; | to execute a written test agreement with the VistA Imaging    |

 ;; | Development Office of the Department of Veterans Affairs,     |

 ;; | telephone (301) 734-0100.                                     |

 ;; |                                                               |

 ;; | The Food and Drug Administration classifies this software as  |

 ;; | a medical device.  As such, it may not be changed in any way. |

 ;; | Modifications to this software may result in an adulterated   |

 ;; | medical device under 21CFR820, the use of which is considered |

 ;; | to be a violation of US Federal Statutes.                     |

 ;; +---------------------------------------------------------------+

 ;;

 Q

 ;

 ;##### DELETES THE PARAMETER FROM THE DEFINITION TREE

 ;

 ; .MAGMSPSDEFS  Reference to a local variable that stores the

 ;               parameter definition tree generated by the

 ;               $$LDMPDEFS^MAGUTL01.

 ;

 ; PNAME         Full name of the parameter: list of names separated

 ;               by the '/' that form the path to the parameter

 ;               descriptor in the definition tree.

 ;

DELMPAR(MAGMSPSDEFS,PNAME) ;

 N I,NAME,PNODE

 S NAME=$P(PNAME,"/")  Q:NAME=""

 S PNODE="MAGMSPSDEFS"

 F I=2:1  S TMP=$P(PNAME,"/",I)  Q:TMP=""  D

 . S PNODE=$NA(@PNODE@("N",NAME)),NAME=TMP

 . Q

 K @PNODE@("N",NAME),@PNODE@("Q",NAME)

 Q

 ;

 ;+++++ RETURNS THE LINE OF THE PARAMETER DEFINITIONS TABLE

 ;

 ; OFFSET        Offset of the line from the tag

 ;

 ; Input Variables

 ; ===============

 ;   MAGRTN, MAGTAG

 ;

 ; Notes

 ; =====

 ;

 ; This is an internal entry point. Do not call it from outside

 ; of this routine.

 ;

GETPDEF(OFFSET) ;

 Q $P($T(@(MAGTAG_"+"_OFFSET_"^"_MAGRTN)),";;",2)

 ;

 ;##### LOADS DEFINITIONS OF MISCELLANEOUS PARAMETERS

 ;

 ; .MAGMSPSDEFS( Reference to a local variable where descriptors

 ;               of the miscellaneous parameters are loaded to.

 ;   "N",

 ;     Name,     Parameter descriptor

 ;                 ^01: (Sub)file number

 ;                 ^02: Field number

 ;                 ^03: Parameter type

 ;                 ^04: Custom flags

 ;       "N",

 ;         Name) Parameter descriptor (record field)

 ;           ...

 ;       "Q",    List of required parameters (record fields)

 ;         Name) ""

 ;   "Q",        List of required parameters

 ;     Name)     ""

 ;

 ;               See the MSPTBL^MAGUTL01 for details.

 ;

 ; TAGRTN        Tag^Routine pair that references the table of

 ;               parameter definitions. See the MSPTBL^MAGUTL01

 ;               for a sample/template.

 ;

 ; [MAGLDFLAGS]  Custom flags (characters) defined by the programmer. 

 ;               If this parameter is defined and not empty, then

 ;               only those definitions that have at least one flag

 ;               included in the value of this parameter are loaded.

 ;

 ; Return Values

 ; =============

 ;           <0  Error descriptor (see $$ERROR^MAGUERR)

 ;            0  Success

 ;

LDMPDEFS(MAGMSPSDEFS,TAGRTN,MAGLDFLAGS) ;

 N MAGRTN,MAGSRCI,MAGTAG,RC

 S MAGTAG=$P(TAGRTN,"^"),MAGRTN=$P(TAGRTN,"^",2)

 S MAGLDFLAGS=$G(MAGLDFLAGS),MAGSRCI=3

 K MAGMSPSDEFS  S RC=$$LDMPDEFZ("MAGMSPSDEFS")

 Q $S(RC<0:RC,1:0)

 ;

 ;+++++ RECURSIVE PARSER OF PARAMETER DEFINITIONS

 ;

 ; DSTNODE       Node of the MAGMSPSDEFS where parameter definitions

 ;               are stored to.

 ;

 ; [RECNAME]     Name of the current record. It is used to detect

 ;               the record boundaries.

 ;

 ; Input Variables

 ; ===============

 ;   MAGRTN, MAGSRCI, MAGTAG

 ;

 ; Output Variables

 ; ================

 ;   MAGSRCI

 ;

 ; Return Values

 ; =============

 ;           <0  Error descriptor (see $$ERROR^MAGUERR)

 ;            0  Success

 ;            1  End of the table

 ;

 ; Notes

 ; =====

 ;

 ; This is an internal entry point. Do not call it from outside

 ; of this routine.

 ;

LDMPDEFZ(DSTNODE,RECNAME) ;

 N BUF,NAME,PNODE,RC,TMP,TYPE

 S RC=0

 F  S MAGSRCI=MAGSRCI+1,BUF=$$GETPDEF(MAGSRCI)  Q:BUF=""  D  Q:RC

 . S BUF=$TR(BUF,"| ",U),NAME=$P(BUF,U,2)  Q:NAME=""

 . ;=== Check custom flags

 . I MAGLDFLAGS'=""  Q:$TR(MAGLDFLAGS,$P(BUF,U,6))=MAGLDFLAGS

 . ;=== If the name is the same as that of the current

 . ;=== record, then this is the end of the record.

 . I NAME=$G(RECNAME)  S RC=2  Q

 . S PNODE=$NA(@DSTNODE@("N",NAME))

 . ;=== Determine the parameter type

 . S TYPE=$P(BUF,U,5)

 . I TYPE["X"  D  Q:RC<0  S $P(BUF,U,5)=TYPE

 . . N DDTYPE,FIELD,FILE,MAGMSG

 . . ;--- Get the field type from the DD

 . . S FILE=$P(BUF,U,3),FIELD=$P(BUF,U,4)

 . . I (FILE'>0)!(FIELD'>0)  S RC=$$ERROR^MAGUERR(-23,,"X")  Q

 . . S DDTYPE=$$GET1^DID(FILE,FIELD,,"TYPE",,"MAGMSG")

 . . I $G(DIERR)  S RC=$$DBS^MAGUERR("MAGMSG")  Q

 . . ;--- Update the parameter type

 . . S TYPE=$TR(TYPE,"DPSWX")

 . . I DDTYPE="DATE/TIME"        S TYPE=TYPE_"D"  Q

 . . I DDTYPE="POINTER"          S TYPE=TYPE_"P"  Q

 . . I DDTYPE="SET"              S TYPE=TYPE_"S"  Q

 . . I DDTYPE="WORD-PROCESSING"  S TYPE=TYPE_"W"  Q

 . . Q

 . ;=== Store the parameter descriptor

 . S @PNODE=$P(BUF,U,3,6)

 . S:TYPE["Q" @DSTNODE@("Q",NAME)=""

 . ;=== Process definitions of a record

 . I TYPE["R"  S RC=$$LDMPDEFZ(PNODE,NAME)  Q

 . Q

 ;===

 Q $S(RC>1:0,'RC:1,1:RC)

 ;

MSPTBL ;+++++ SAMPLE/TEMPLATE OF THE PARAMETER DEFINITONS TABLE

 ;;==================================================================

 ;;| Parameter  | File  |Field|Type |Flags|        Comment          |

 ;;|------------+-------+-----+-----+-----+-------------------------|

 ;;|DTIS        |2005   |   7 | DHQ |     | DATE/TIME IMAGE SAVED   |

 ;;|DESCR       |       |     | W   |     |                         |

 ;;|OBJGROUP    |       |     | RM  |     |                         |

 ;;|  GROUP     |2005.04| .01 | PQ  |     |                         |

 ;;|  IMGNUM    |2005.04|   2 |     |     |                         |

 ;;|OBJGROUP    |       |     |     |     |                         |

 ;;|ORIGIN      |2005   |  45 |  M  |     |                         |

 ;;==================================================================

 ;

 ; Parameter     Parameter name. It must be unique on the top level

 ;               or inside each record definition (e.g. OBJGROUP) and 

 ;               must not contain spaces.

 ;

 ; File          If the file and field numbers are defined, then

 ; Field         values of the parameter are validated according to

 ;               the field data dictionary (using the CHK^DIE).

 ;

 ;               NOTE: This simple validation will not work for those 

 ;                     fields that have input transform that depend

 ;                     on other fields and/or records.

 ;

 ; Type          Parameter type:

 ;                 D - Date/time,  P - Pointer,

 ;                 R - Record,     S - Set of codes

 ;                 W - Word processing

 ;                 X - Set the type according to the field type from

 ;                     the DD (the File and Field must be provided).

 ;                     The 'X' itself is removed from the descriptor.

 ;               and modifiers:

 ;                 H - Date/time in HL7 format (TS)

 ;                 M - Multi-value parameter

 ;                 Q - Required parameter

 ;

 ; Flags         Custom flags defined by the programmer. Use them to

 ;               control what definitions are loaded by the

 ;               $$LDMPDEFS^MAGUTL01 function (see the MAGLDFLAGS

 ;               parameter of the function for more details).

 ;

 Q

--- Routine Detail   --- with STRUCTURED ROUTINE LISTING ---MAGUTL01   8089     printed  Apr 23, 2025@18:23:38                                                                                                                                                                                                    Page 2

MAGUTL01  ;WOIFO/SG - PARAMETERS AND VALIDATION UTILITIES ; 3/9/09 12:53pm

 +1       ;;3.0;IMAGING;**93**;Dec 02, 2009;Build 163

 +2       ;; Per VHA Directive 2004-038, this routine should not be modified.

 +3       ;; +---------------------------------------------------------------+

 +4       ;; | Property of the US Government.                                |

 +5       ;; | No permission to copy or redistribute this software is given. |

 +6       ;; | Use of unreleased versions of this software requires the user |

 +7       ;; | to execute a written test agreement with the VistA Imaging    |

 +8       ;; | Development Office of the Department of Veterans Affairs,     |

 +9       ;; | telephone (301) 734-0100.                                     |

 +10      ;; |                                                               |

 +11      ;; | The Food and Drug Administration classifies this software as  |

 +12      ;; | a medical device.  As such, it may not be changed in any way. |

 +13      ;; | Modifications to this software may result in an adulterated   |

 +14      ;; | medical device under 21CFR820, the use of which is considered |

 +15      ;; | to be a violation of US Federal Statutes.                     |

 +16      ;; +---------------------------------------------------------------+

 +17      ;;

 +18       QUIT 

 +19      ;

 +20      ;##### DELETES THE PARAMETER FROM THE DEFINITION TREE

 +21      ;

 +22      ; .MAGMSPSDEFS  Reference to a local variable that stores the

 +23      ;               parameter definition tree generated by the

 +24      ;               $$LDMPDEFS^MAGUTL01.

 +25      ;

 +26      ; PNAME         Full name of the parameter: list of names separated

 +27      ;               by the '/' that form the path to the parameter

 +28      ;               descriptor in the definition tree.

 +29      ;

DELMPAR(MAGMSPSDEFS,PNAME) ;

 +1        NEW I,NAME,PNODE

 +2        SET NAME=$PIECE(PNAME,"/")

           if NAME=""

               QUIT 

 +3        SET PNODE="MAGMSPSDEFS"

 +4        FOR I=2:1

               SET TMP=$PIECE(PNAME,"/",I)

               if TMP=""

                   QUIT 

               Begin DoDot:1

 +5                SET PNODE=$NAME(@PNODE@("N",NAME))

                   SET NAME=TMP

 +6                QUIT 

               End DoDot:1

 +7        KILL @PNODE@("N",NAME),@PNODE@("Q",NAME)

 +8        QUIT 

 +9       ;

 +10      ;+++++ RETURNS THE LINE OF THE PARAMETER DEFINITIONS TABLE

 +11      ;

 +12      ; OFFSET        Offset of the line from the tag

 +13      ;

 +14      ; Input Variables

 +15      ; ===============

 +16      ;   MAGRTN, MAGTAG

 +17      ;

 +18      ; Notes

 +19      ; =====

 +20      ;

 +21      ; This is an internal entry point. Do not call it from outside

 +22      ; of this routine.

 +23      ;

GETPDEF(OFFSET) ;

 +1        QUIT $PIECE($TEXT(@(MAGTAG_"+"_OFFSET_"^"_MAGRTN)),";;",2)

 +2       ;

 +3       ;##### LOADS DEFINITIONS OF MISCELLANEOUS PARAMETERS

 +4       ;

 +5       ; .MAGMSPSDEFS( Reference to a local variable where descriptors

 +6       ;               of the miscellaneous parameters are loaded to.

 +7       ;   "N",

 +8       ;     Name,     Parameter descriptor

 +9       ;                 ^01: (Sub)file number

 +10      ;                 ^02: Field number

 +11      ;                 ^03: Parameter type

 +12      ;                 ^04: Custom flags

 +13      ;       "N",

 +14      ;         Name) Parameter descriptor (record field)

 +15      ;           ...

 +16      ;       "Q",    List of required parameters (record fields)

 +17      ;         Name) ""

 +18      ;   "Q",        List of required parameters

 +19      ;     Name)     ""

 +20      ;

 +21      ;               See the MSPTBL^MAGUTL01 for details.

 +22      ;

 +23      ; TAGRTN        Tag^Routine pair that references the table of

 +24      ;               parameter definitions. See the MSPTBL^MAGUTL01

 +25      ;               for a sample/template.

 +26      ;

 +27      ; [MAGLDFLAGS]  Custom flags (characters) defined by the programmer. 

 +28      ;               If this parameter is defined and not empty, then

 +29      ;               only those definitions that have at least one flag

 +30      ;               included in the value of this parameter are loaded.

 +31      ;

 +32      ; Return Values

 +33      ; =============

 +34      ;           <0  Error descriptor (see $$ERROR^MAGUERR)

 +35      ;            0  Success

 +36      ;

LDMPDEFS(MAGMSPSDEFS,TAGRTN,MAGLDFLAGS) ;

 +1        NEW MAGRTN,MAGSRCI,MAGTAG,RC

 +2        SET MAGTAG=$PIECE(TAGRTN,"^")

           SET MAGRTN=$PIECE(TAGRTN,"^",2)

 +3        SET MAGLDFLAGS=$GET(MAGLDFLAGS)

           SET MAGSRCI=3

 +4        KILL MAGMSPSDEFS

           SET RC=$$LDMPDEFZ("MAGMSPSDEFS")

 +5        QUIT $SELECT(RC<0:RC,1:0)

 +6       ;

 +7       ;+++++ RECURSIVE PARSER OF PARAMETER DEFINITIONS

 +8       ;

 +9       ; DSTNODE       Node of the MAGMSPSDEFS where parameter definitions

 +10      ;               are stored to.

 +11      ;

 +12      ; [RECNAME]     Name of the current record. It is used to detect

 +13      ;               the record boundaries.

 +14      ;

 +15      ; Input Variables

 +16      ; ===============

 +17      ;   MAGRTN, MAGSRCI, MAGTAG

 +18      ;

 +19      ; Output Variables

 +20      ; ================

 +21      ;   MAGSRCI

 +22      ;

 +23      ; Return Values

 +24      ; =============

 +25      ;           <0  Error descriptor (see $$ERROR^MAGUERR)

 +26      ;            0  Success

 +27      ;            1  End of the table

 +28      ;

 +29      ; Notes

 +30      ; =====

 +31      ;

 +32      ; This is an internal entry point. Do not call it from outside

 +33      ; of this routine.

 +34      ;

LDMPDEFZ(DSTNODE,RECNAME) ;

 +1        NEW BUF,NAME,PNODE,RC,TMP,TYPE

 +2        SET RC=0

 +3        FOR 

               SET MAGSRCI=MAGSRCI+1

               SET BUF=$$GETPDEF(MAGSRCI)

               if BUF=""

                   QUIT 

               Begin DoDot:1

 +4                SET BUF=$TRANSLATE(BUF,"| ",U)

                   SET NAME=$PIECE(BUF,U,2)

                   if NAME=""

                       QUIT 

 +5       ;=== Check custom flags

 +6                IF MAGLDFLAGS'=""

                       if $TRANSLATE(MAGLDFLAGS,$PIECE(BUF,U,6))=MAGLDFLAGS

                           QUIT 

 +7       ;=== If the name is the same as that of the current

 +8       ;=== record, then this is the end of the record.

 +9                IF NAME=$GET(RECNAME)

                       SET RC=2

                       QUIT 

 +10               SET PNODE=$NAME(@DSTNODE@("N",NAME))

 +11      ;=== Determine the parameter type

 +12               SET TYPE=$PIECE(BUF,U,5)

 +13               IF TYPE["X"

                       Begin DoDot:2

 +14                       NEW DDTYPE,FIELD,FILE,MAGMSG

 +15      ;--- Get the field type from the DD

 +16                       SET FILE=$PIECE(BUF,U,3)

                           SET FIELD=$PIECE(BUF,U,4)

 +17                       IF (FILE'>0)!(FIELD'>0)

                               SET RC=$$ERROR^MAGUERR(-23,,"X")

                               QUIT 

 +18                       SET DDTYPE=$$GET1^DID(FILE,FIELD,,"TYPE",,"MAGMSG")

 +19                       IF $GET(DIERR)

                               SET RC=$$DBS^MAGUERR("MAGMSG")

                               QUIT 

 +20      ;--- Update the parameter type

 +21                       SET TYPE=$TRANSLATE(TYPE,"DPSWX")

 +22                       IF DDTYPE="DATE/TIME"

                               SET TYPE=TYPE_"D"

                               QUIT 

 +23                       IF DDTYPE="POINTER"

                               SET TYPE=TYPE_"P"

                               QUIT 

 +24                       IF DDTYPE="SET"

                               SET TYPE=TYPE_"S"

                               QUIT 

 +25                       IF DDTYPE="WORD-PROCESSING"

                               SET TYPE=TYPE_"W"

                               QUIT 

 +26                       QUIT 

                       End DoDot:2

                       if RC<0

                           QUIT 

                       SET $PIECE(BUF,U,5)=TYPE

 +27      ;=== Store the parameter descriptor

 +28               SET @PNODE=$PIECE(BUF,U,3,6)

 +29               if TYPE["Q"

                       SET @DSTNODE@("Q",NAME)=""

 +30      ;=== Process definitions of a record

 +31               IF TYPE["R"

                       SET RC=$$LDMPDEFZ(PNODE,NAME)

                       QUIT 

 +32               QUIT 

               End DoDot:1

               if RC

                   QUIT 

 +33      ;===

 +34       QUIT $SELECT(RC>1:0,'RC:1,1:RC)

 +35      ;

MSPTBL    ;+++++ SAMPLE/TEMPLATE OF THE PARAMETER DEFINITONS TABLE

 +1       ;;==================================================================

 +2       ;;| Parameter  | File  |Field|Type |Flags|        Comment          |

 +3       ;;|------------+-------+-----+-----+-----+-------------------------|

 +4       ;;|DTIS        |2005   |   7 | DHQ |     | DATE/TIME IMAGE SAVED   |

 +5       ;;|DESCR       |       |     | W   |     |                         |

 +6       ;;|OBJGROUP    |       |     | RM  |     |                         |

 +7       ;;|  GROUP     |2005.04| .01 | PQ  |     |                         |

 +8       ;;|  IMGNUM    |2005.04|   2 |     |     |                         |

 +9       ;;|OBJGROUP    |       |     |     |     |                         |

 +10      ;;|ORIGIN      |2005   |  45 |  M  |     |                         |

 +11      ;;==================================================================

 +12      ;

 +13      ; Parameter     Parameter name. It must be unique on the top level

 +14      ;               or inside each record definition (e.g. OBJGROUP) and 

 +15      ;               must not contain spaces.

 +16      ;

 +17      ; File          If the file and field numbers are defined, then

 +18      ; Field         values of the parameter are validated according to

 +19      ;               the field data dictionary (using the CHK^DIE).

 +20      ;

 +21      ;               NOTE: This simple validation will not work for those 

 +22      ;                     fields that have input transform that depend

 +23      ;                     on other fields and/or records.

 +24      ;

 +25      ; Type          Parameter type:

 +26      ;                 D - Date/time,  P - Pointer,

 +27      ;                 R - Record,     S - Set of codes

 +28      ;                 W - Word processing

 +29      ;                 X - Set the type according to the field type from

 +30      ;                     the DD (the File and Field must be provided).

 +31      ;                     The 'X' itself is removed from the descriptor.

 +32      ;               and modifiers:

 +33      ;                 H - Date/time in HL7 format (TS)

 +34      ;                 M - Multi-value parameter

 +35      ;                 Q - Required parameter

 +36      ;

 +37      ; Flags         Custom flags defined by the programmer. Use them to

 +38      ;               control what definitions are loaded by the

 +39      ;               $$LDMPDEFS^MAGUTL01 function (see the MAGLDFLAGS

 +40      ;               parameter of the function for more details).

 +41      ;

 +42       QUIT