Home   Package List   Routine Alphabetical List   Global Alphabetical List   FileMan Files List   FileMan Sub-Files List   Package Component Lists   Package-Namespace Mapping  
Routine: MAGUERR

MAGUERR.m

Go to the documentation of this file. 
  1. MAGUERR ;WOIFO/SG - ERROR HANDLING UTILITIES ; 3/9/09 12:53pm
  1.  ;;3.0;IMAGING;**93**;Dec 02, 2009;Build 163
  1.  ;; Per VHA Directive 2004-038, this routine should not be modified.
  1.  ;; +---------------------------------------------------------------+
  1.  ;; | Property of the US Government.                                |
  1.  ;; | No permission to copy or redistribute this software is given. |
  1.  ;; | Use of unreleased versions of this software requires the user |
  1.  ;; | to execute a written test agreement with the VistA Imaging    |
  1.  ;; | Development Office of the Department of Veterans Affairs,     |
  1.  ;; | telephone (301) 734-0100.                                     |
  1.  ;; |                                                               |
  1.  ;; | The Food and Drug Administration classifies this software as  |
  1.  ;; | a medical device.  As such, it may not be changed in any way. |
  1.  ;; | Modifications to this software may result in an adulterated   |
  1.  ;; | medical device under 21CFR820, the use of which is considered |
  1.  ;; | to be a violation of US Federal Statutes.                     |
  1.  ;; +---------------------------------------------------------------+
  1.  ;;
  1.  ; * Error codes are negative numbers.
  1.  ;
  1.  ; * The corresponding error messages are stored in the DIALOG file
  1.  ;   (#.84). Dialog numbers are calculated as follows:
  1.  ;
  1.  ;         Dialog# = 20050000 - (ErrorCode / 1000).
  1.  ;
  1.  ;   For example, dialog number for the error code -9 is 20050000.009.
  1.  ;
  1.  ; * A message itself is stored in the second "^"-piece of the dialog
  1.  ;   text line. The first piece determines the problem type:
  1.  ;
  1.  ;     I - Information. No actions are required.
  1.  ;
  1.  ;     W - Warning. There was a problem but the code was/will be
  1.  ;         able to ignore/recover and continue. User input errors
  1.  ;         have this type as well.
  1.  ;
  1.  ;     E - Error. The code encountered a major problem and could
  1.  ;         not continue. Data, code, or both should be fixed!
  1.  ;
  1.  ; TEMPORARY ERROR STORAGE
  1.  ; =======================
  1.  ;
  1.  ; ^TMP("MAG-ERRROR-STORAGE",$J,
  1.  ;   Seq#,
  1.  ;     0)                Error Descriptor (see the $$ERROR^MAGUERR)
  1.  ;                         ^01: Error code
  1.  ;                         ^02: Error message
  1.  ;                         ^03: Error location (TAG~ROUTINE)
  1.  ;                         ^04: Type ("W" - warning, "E" - error)
  1.  ;     1,Seq#)           Error details text (optional)
  1.  ;
  1.  ; Information messages (the "I" type) are never stored regardless
  1.  ; of the mode set by the CLEAR^MAGUERR.
  1.  ;
  1.  Q
  1.  ;
  1.  ;##### INITIALIZES THE ERROR STORAGE
  1.  ;
  1.  ; [ENABLE]      Enable/disable error storage (0|1). If the storage
  1.  ;               enabled, the $$ERROR function stores the error
  1.  ;               descriptors there. Otherwise, only the latest
  1.  ;               error descriptor is accessible (the result value
  1.  ;               of the $$ERROR or $$DBS functions).
  1.  ;
  1.  ; This procedure also clears the error storage (regardless of the
  1.  ; value of the ENABLE parameter).
  1.  ;
  1. CLEAR(ENABLE) ;
  1.  S:'($D(ENABLE)#10) ENABLE=$D(^TMP("MAG-ERRROR-STORAGE",$J))#10
  1.  K ^TMP("MAG-ERRROR-STORAGE",$J)
  1.  S:ENABLE ^TMP("MAG-ERRROR-STORAGE",$J)=""
  1.  D CLEAN^DILF
  1.  Q
  1.  ;
  1.  ;##### CHECKS THE ERRORS AFTER A FILEMAN DBS CALL
  1.  ;
  1.  ; MAG8MSG       Closed reference of the error message array
  1.  ;               (from a DBS call). If this parameter is empty,
  1.  ;               then the ^TMP("DIERR",$J) is assumed.
  1.  ;
  1.  ; [FILE]        File number used in the DBS call.
  1.  ; [IENS]        IENS used in the DBS call.
  1.  ;
  1.  ; This function checks the DIERR and @MAG8MSG variables after
  1.  ; a FileMan DBS call and returns the error descriptor in case of
  1.  ; error(s).
  1.  ; 
  1.  ; Return Values
  1.  ; =============
  1.  ;           <0  -9^Message text^Error location^Message type
  1.  ;            0  No errors
  1.  ;
  1.  ; Notes
  1.  ; =====
  1.  ;
  1.  ; If the error storage is enabled (see the CLEAR^MAGUERR), the
  1.  ; messages returned by the FileMan call are recorded along with
  1.  ; the error descriptor.  Otherwise, they are discarded.
  1.  ; 
  1.  ; This entry point can also be called as a procedure:
  1.  ; D DBS^MAGUERR(...) if you do not need its return value.
  1.  ;
  1. DBS(MAG8MSG,FILE,IENS) ;
  1.  I '$G(DIERR)  Q:$QUIT 0  Q
  1.  N MSGTEXT,TMP
  1.  ;--- Format the FileMan error messages
  1.  D MSG^DIALOG("AE",.MSGTEXT,,,$G(MAG8MSG)),CLEAN^DILF
  1.  ;--- Record the error message
  1.  S TMP=$S($G(FILE):"; File #"_FILE,1:"")
  1.  S:$G(IENS)'="" TMP=TMP_"; IENS: """_IENS_""""
  1.  S TMP=$$ERROR(-9,.MSGTEXT,TMP)
  1.  Q:$QUIT TMP  Q
  1.  ;
  1.  ;##### GENERATES THE ERROR MESSAGE
  1.  ;
  1.  ; ERRCODE       Error code (negative number).
  1.  ;
  1.  ;               If the error code has the 'S' suffix (e.g. "-3S"),
  1.  ;               then the error info is NOT stored regardless of the
  1.  ;               storage mode set by the CLEAR^MAGUERR.
  1.  ;
  1.  ; [[.]MAGINFO]  Optional additional information: either a string or
  1.  ;               a reference to a local array that contains strings
  1.  ;               prepared for storage in a word processing field
  1.  ;               (first level nodes; no 0-nodes).
  1.  ;
  1.  ; [ARG1-ARG5]   Optional parameters for $$MSG^MAGUERR.
  1.  ;
  1.  ; Return Values
  1.  ; =============
  1.  ;           <0  Error code^Message text^Error location^Message type
  1.  ;            0  Ok (if ERRCODE'<0)
  1.  ;
  1.  ; Notes
  1.  ; =====
  1.  ;
  1.  ; "^" is replaced with "~" in the error location stored in the 3rd
  1.  ; piece of the error descriptor.
  1.  ;
  1.  ; If error storage is enabled by the CLEAR^MAGUERR and type is other 
  1.  ; than information (I), then this procedure saves the message info
  1.  ; to the temporary error storage.
  1.  ;
  1.  ; This entry point can also be called as a procedure:
  1.  ; D ERROR^MAGUERR(...) if you do not need its return value.
  1.  ;
  1. ERROR(ERRCODE,MAGINFO,ARG1,ARG2,ARG3,ARG4,ARG5) ;
  1.  I ERRCODE'<0  Q:$QUIT 0  Q
  1.  N MSG,PLACE,SL,TYPE
  1.  ;--- Get the error location
  1.  S SL=$STACK(-1)-1,PLACE=""
  1.  F  Q:SL'>0  D  Q:'(PLACE[$T(+0))  S SL=SL-1
  1.  . S PLACE=$P($STACK(SL,"PLACE")," ")
  1.  . Q
  1.  ;--- Prepare the additional information
  1.  I $D(MAGINFO)=1  S MSG=MAGINFO  K MAGINFO  S MAGINFO(1)=MSG
  1.  ;--- Prepare the message descriptor
  1.  S MSG=$$MSG(+ERRCODE,.TYPE,.ARG1,.ARG2,.ARG3,.ARG4,.ARG5)
  1.  S MSG=(+ERRCODE)_U_MSG_U_$TR(PLACE,U,"~")_U_TYPE
  1.  ;--- Store the error info
  1.  I TYPE'="I",ERRCODE'["S"  D STORE(MSG,.MAGINFO)
  1.  ;---
  1.  Q:$QUIT MSG  Q
  1.  ;
  1.  ;##### GENERATES THE 'INVALID PARAMETER VALUE' ERROR
  1.  ;
  1.  ; MAG8NAME      Closed reference to the variable/node
  1.  ;
  1.  ; [DSPNAME]     Display name of the parameter. If this parameter is
  1.  ;               defined and not empty, its value is used as the
  1.  ;               parameter name in the error message (instead of the
  1.  ;               name passed in the MAG8NAME parameter).
  1.  ;
  1.  ; Return Values
  1.  ; =============
  1.  ;               -3^Message text^Error location^Message type
  1.  ;
  1.  ; Notes
  1.  ; =====
  1.  ;
  1.  ; This entry point can also be called as a procedure:
  1.  ; D IPVE^MAGUERR(...) if you do not need its return value.
  1.  ;
  1. IPVE(MAG8NAME,DSPNAME) ;
  1.  N MAG8RC
  1.  S MAG8RC=$S($D(@MAG8NAME)#2:"'"_@MAG8NAME_"'",1:"<UNDEFINED>")
  1.  S MAG8RC=$$ERROR(-3,,$S($G(DSPNAME)'="":DSPNAME,1:MAG8NAME),MAG8RC)
  1.  Q:$QUIT MAG8RC  Q
  1.  ;
  1.  ;##### RETURNS THE TEXT AND TYPE OF THE MESSAGE
  1.  ;
  1.  ; ERRCODE       Error code
  1.  ;
  1.  ; [.TYPE]       Reference to a local variable where the problem
  1.  ;               type is returned ("I" -  Information, "W" - warning, 
  1.  ;               "E" - error).
  1.  ;
  1.  ; [ARG1-ARG5]   Optional parameters that substitute the |n| "windows"
  1.  ;               in the text of the message (for example, the |2| will
  1.  ;               be substituted by the value of the ARG2).
  1.  ;
  1.  ; Return Values
  1.  ; =============
  1.  ;               Text of the error message
  1.  ;
  1.  ; Notes
  1.  ; =====
  1.  ;
  1.  ; The "^" is replaced with the "~" in the message text.
  1.  ;
  1. MSG(ERRCODE,TYPE,ARG1,ARG2,ARG3,ARG4,ARG5) ;
  1.  Q:ERRCODE'<0 ""
  1.  N ARG,I1,I2,MSG
  1.  ;--- Get a descriptor of the message
  1.  S MSG=$$EZBLD^DIALOG(20050000-(ERRCODE/1000))
  1.  ;--- Parse and validate the descriptor
  1.  S TYPE=$E(MSG),MSG=$P(MSG,U,2,999)
  1.  S:("IWE"'[TYPE)!(TYPE="") TYPE="E"
  1.  Q:MSG?." " "Unknown error ("_ERRCODE_")"
  1.  ;--- Substitute parameters
  1.  S I1=2
  1.  F  S I1=$F(MSG,"|",I1-1)  Q:'I1  D
  1.  . S I2=$F(MSG,"|",I1)  Q:'I2
  1.  . X "S ARG=$G(ARG"_+$TR($E(MSG,I1,I2-2)," ")_")"
  1.  . S $E(MSG,I1-1,I2-1)=ARG
  1.  . Q
  1.  Q $TR($$TRIM^XLFSTR(MSG),U,"~")
  1.  ;
  1.  ;##### ASSIGNS THE DEFAULT ERROR HANDLER
  1.  ;
  1.  ; [RCVNAME]     Name of a variable for the error code
  1.  ;
  1.  ;               See the RTEHNDLR^MAGUERR1 for more details and the
  1.  ;               SETPROPS^MAGGA02 for a usage example.
  1.  ;
  1. SETDEFEH(RCVNAME) ;
  1.  S $ECODE=""
  1.  S $ETRAP="D RTEHNDLR^MAGUERR1("_$$DDQ^MAGUTL05($G(RCVNAME))_")"
  1.  Q
  1.  ;
  1.  ;##### STORES THE ERROR INFO
  1.  ;
  1.  ; ERROR         Error descriptor
  1.  ;
  1.  ; [.MAGINFO]    Reference to a local array with additional
  1.  ;               information
  1.  ;
  1. STORE(ERROR,MAGINFO) ;
  1.  Q:'$D(^TMP("MAG-ERRROR-STORAGE",$J))
  1.  N IEN
  1.  S IEN=$O(^TMP("MAG-ERRROR-STORAGE",$J," "),-1)+1
  1.  S ^TMP("MAG-ERRROR-STORAGE",$J,IEN,0)=ERROR
  1.  M ^TMP("MAG-ERRROR-STORAGE",$J,IEN,1)=MAGINFO
  1.  Q