ERRCHECK Procedure

Standard Library procedure which provides comprehensive error checking that can be used by any PV-WAVE routine.

Usage

    ERRCHECK, v

Input Parameters

v—The variable to be checked.

Keywords

Note: If v does not comply with restrictions imposed by keywords below then an appropriate error message is issued.

Kwrd—If set then v is treated like an optional parameter: that is to say, error checking is performed only if v is defined.

Type—On input, an array of acceptable data types: SIZE(v,/Type) must equal Type(i) for some i. Type = [1,2,3,4,5,6,12,13] can be abbreviated as Type = –1. On output, Type is the actual data type of v. Output occurs even if this keyword is undefined on input.

Ndim—On input, an array of acceptable dimensionalites: SIZE(v,/Ndim) must equal Ndim(i) for some i. Use Ndim = 0 for scalars and Ndim = –1 for arbitrary arrays. On output, Ndim is the actual number of dimensions of v. Output occurs even if this keyword is undefined on input.

Dims—On input, a (2,*) array of bounds on dimension length: d = SIZE(v,/Dimension) must obey Dims(0,i) ≤ d(i) ≤ Dims(1,i). If Dims(i,j) = 0 then that bound is not enforced. On output, Dims is an Ndim-element array of the dimensions of v. Output occurs even if this keyword is undefined on input.

Edim—On input, an array of exact dimension lengths: (SIZE(v,/Dimension))(i) must equal Edim(i) for each i, unless Edim(i) = 0, and then that length is not enforced. On output, Edim is the array of dimensions of v: SIZE(v,/Dimension). Output occurs even if this keyword is undefined on input.

Rnge—On input, a string indicating bounds on numerical value: Any of the four interval types can be indicated by setting Rnge to one of:

  • '(lo,hi)'—which means lo < x < hi

  • '(lo,hi]'—which means lo < x ≤ hi

  • '[lo,hi)'—which means lo ≤ x < hi

  • '[lo,hi]'—which means lo ≤ x ≤ hi

Half-bounded intervals are indicated by the substrings –inf or inf, for example '[–inf,1.5]' or '[–1E4,inf]' (the substrings –inf and inf are not to be confused with IEEE representations of –infinity or infinity). On output, Rnge is the 2-element array [min(v),max(v)]. Output occurs even if this keyword is undefined on input.

Nout—String array containing the names of ERRCHECK keywords for which input values must not change on output. This is useful when the same input value is to be used in multiple calls to ERRCHECK, so the value is not overwritten at each call to ERRCHECK.

Actn—The ON_ERROR action to take when an error occurs. The default is 2. Refer to the ON_ERROR Procedure for additional details.

Discussion

This procedure enables the PV‑WAVE user to quickly and cleanly do exhaustive error checking, complete with error messages. Any parameter to the user’s routine can be exhaustively error checked with a single call to ERRCHECK. Keywords allow virtually any combination of error checking to be performed. If the error checking succeeds, in other words the variable passes all size, type, and dimension checks, then PV-WAVE program execution continues. On the other hand, if any of the checks fail then ERRCHECK passes control to the MESSAGE procedure and normal PV‑WAVE error condition handling occurs.

Examples

data = INDGEN(2,3)
PM, data
; PV-WAVE prints the following:
; 0       2       4
; 1       3       5

Although the data is undefined, no error is returned in the following example because the Kwrd keyword is set.

ERRCHECK, undef, Type=2, /Kwrd

The following two lines of code demonstrate Type errors.

ERRCHECK, undef, Type=2 
; PV-WAVE prints the following:
; % $MAIN$: SIZE(undef,/Type) must equal 2
; % Execution halted at ERRCHECK <errcheck.pro(  90)>  (MESSAGE).
; % Called from $MAIN$ .

ERRCHECK, data, Type=[0,1] 
; PV-WAVE prints the following:
; % $MAIN$: SIZE(data,/Type) must equal 0, or 1
; % Execution halted at ERRCHECK <errcheck.pro(  90)>  (MESSAGE).
; % Called from $MAIN$ .

The following two lines of code demonstrate number of dimensions errors.

ERRCHECK, data, Type=2, Ndim=0 
; PV-WAVE prints the following:
; % $MAIN$: SIZE(data,/Ndimensions) must equal 0
; % Execution halted at ERRCHECK <errcheck.pro( 102)>  (MESSAGE).
; % Called from $MAIN$ .

ERRCHECK, data, Type=[1,2], Ndim=[0,1] 
; PV-WAVE prints the following:
; % $MAIN$: SIZE(data,/Ndimensions) must equal 0, or 1
; % Execution halted at ERRCHECK <errcheck.pro( 102)>  (MESSAGE).
; % Called from $MAIN$ .

The following two lines of code demonstrate dimension length errors.

ERRCHECK, data, Ndim=2, Edim=[3,3] 
; PV-WAVE prints the following:
; % $MAIN$: (SIZE(data,/Dimensions))(0) must equal 3
; % Execution halted at ERRCHECK <errcheck.pro( 145)>  (MESSAGE).
; % Called from $MAIN$ .
ERRCHECK, data, Ndim=2, Dims=[[3,3],[3,3]] 
; PV-WAVE prints the following:
; % $MAIN$: (SIZE(data,/Dimensions))(0) must equal 3
; % Execution halted at ERRCHECK <errcheck.pro( 128)>  (MESSAGE).
; % Called from $MAIN$ .

The following three lines of code demonstrate dimension length errors.

ERRCHECK, data, Ndim=[1,2], Edim=[2,2] 
; PV-WAVE prints the following:
; % $MAIN$: (SIZE(data,/Dimensions))(1) must equal 2
; % Execution halted at ERRCHECK <errcheck.pro( 145)>  (MESSAGE).
; % Called from $MAIN$ .

ERRCHECK, data, Ndim=[1,2], Dims=[[2,2],[0,2]] 
; PV-WAVE prints the following:
; % $MAIN$:(SIZE(data,/Dimensions))(1) must be less than or 
; equal 2
; % Execution halted at ERRCHECK <errcheck.pro( 118)>  (MESSAGE).
; % Called from $MAIN$ .

ERRCHECK, data, Type=2, Dims=[[2,2],[4,0]] 
; PV-WAVE prints the following:
; % $MAIN$: (SIZE(data,/Dimensions))(1) must be greater than or
; equal 4
; % Execution halted at ERRCHECK <errcheck.pro( 122)>  (MESSAGE).
; % Called from $MAIN$ .

The following examples do not return an error.

ERRCHECK, data, Type=2, Edim=[0,3] 
ERRCHECK, data, Type=2, Edim=[2,0] 
ERRCHECK, data, Type=2, Dims=[[0,0],[0,4]] 
ERRCHECK, data, Ndim=2, Dims=[[2,0],[3,3]] 
ERRCHECK, data, Dims=[[2,2],[3,3]] 
ERRCHECK, data, Ndim=2, Rnge='(-1e-9,6)' 
ERRCHECK, data, Rnge='[0,6)' 
ERRCHECK, data, Type=2, Ndim=2, Rnge='[0,5]' 
ERRCHECK, data, Ndim=2, Rnge='[-inf,9]'

The following examples demonstrate data range errors. In the first example, 0 is not included in the range, and in the second example, 5 is not included (but 0 is).

ERRCHECK, data, Type=2, Rnge='(0,6)' 
; PV-WAVE prints the following:
; % $MAIN$: Values in data must be in the interval (0,6)
; % Execution halted at ERRCHECK <errcheck.pro( 165)>  (MESSAGE).
; % Called from $MAIN$ .

ERRCHECK, data, Type=2, Ndim=2, Rnge='[0,5)' 
; PV-WAVE prints the following:
; % $MAIN$: Values in data must be in the interval [0,5)
; % Execution halted at ERRCHECK <errcheck.pro( 165)>  (MESSAGE).
; % Called from $MAIN$ .

The following examples demonstrate how to capture output and how to suppress it.

ERRCHECK, data, Type=d0
ERRCHECK, data, Type=d1, Nout='Type' 

; Use the INFO procedure to test if the output was captured.
INFO, d0 
; PV-WAVE prints the following:
; D0              LONG      =            2

INFO, d1 
; PV-WAVE prints the following:
; D1              UNDEFINED = <Undefined>