;$Id: sum_2d_array.pro,v 1.1 1998/10/19 20:51:10 beth Exp $
;;
;; NAME:
;;
;; 	sum_2d_array.pro
;;
;; PURPOSE:
;;	This IDL procedure calls a CALL_EXTERNAL routine which demonstrates
;;      how to pass IDL structures to external code.  The purpose of this
;;      code is to:
;;      1) implement a simple interface to the external code.
;;      2) check the type of arguments that will be passed to the external code
;;
;; CATEGORY:
;;	Dynamic Link
;;
;; CALLING SEQUENCE:
;;	This routine is called from IDL using the following commands:
;;      IDL>sum_2d_array
;;      or
;;      IDL>sum_2d_array,dindgen(20,20),5,10,5,10
;;
;; INPUTS:
;;      arr - a 2 dimensional IDL array of type double
;;      x_start - X index of the start of the subsection
;;      x_end   - X index of the end of the subsection
;;      y_start - Y index of the start of the subsection
;;      y_end   - Y index of the end of the subsection
;;
;;
;; KEYWORDS:
;;      DEBUG - If this keyword is unset, this routine will return to the
;;              caller on any error. If this keyword is set, this routine will
;;              stop at the point of the error.
;; SIDE EFFECTS:
;;	None.
;;
;; RESTRICTIONS:
;;      None.
;;
;; MODIFICATION HISTORY:
;;	Written May, 1998 JJG
;;
PRO sum_2d_array,arr,x_start,x_end,y_start,y_end,DEBUG = debug

    if NOT(KEYWORD_SET(debug)) THEN ON_ERROR,2

    ;check the layout of the array.
    arr = (SIZE(arr,/TNAME) EQ 'UNDEFINED') ? DINDGEN(20,20) : DOUBLE(arr)

    sz = SIZE(arr,/STRUCTURE)
    IF (sz.n_dimensions NE 2) THEN MESSAGE,'ARR must be 2 dimensional'

    ;x_start must be a nonegative scalar long
    x_start = (SIZE(x_start,/TNAME) EQ 'UNDEFINED') ? 0L : LONG(x_start[0] > 0)
    x_size =  sz.dimensions[0]
    ;x_end must be a scalar long smaller than the x_size of the array.
    x_end = (SIZE(x_end,/TNAME) EQ 'UNDEFINED') ? x_size - 1 : $
             LONG(x_end[0] < (x_size - 1))


    ;make sure x_start and y_end make sense
    IF (x_start GT x_end) THEN $
        MESSAGE,'X_START must be less than or equal to X_END'

    ;y_start must be a nonegative scalar long
    y_start = (SIZE(y_start,/TNAME) EQ 'UNDEFINED') ? 0L : LONG(y_start[0] > 0)
    y_size =  sz.dimensions[1]
    ;y_end must be a scalar long smaller than the y_size of the array.
    y_end = (SIZE(y_end,/TNAME) EQ 'UNDEFINED') ? y_size - 1 : $
             LONG(y_end[0] < (y_size - 1))

    ;make sure y_start and y_end make sense
    IF (y_start GT y_end) THEN $
        MESSAGE,'Y_START must be less than or equal to Y_END'

    PRINT,'Calling external function with:'
    HELP,arr,x_start,x_end,x_size,y_start,y_end,y_size

    result =  CALL_EXTERNAL(lib_name('call_examples'),'sum_2d_array',$
                            arr,x_start,x_end,x_size,$
                            y_start,y_end,y_size,/D_VALUE,/PORTABLE)

    ;this result should be equivalent to what the C code is doing
    check = TOTAL(arr[x_start:x_end,y_start:y_end],/DOUBLE)

    IF (result NE check ) THEN BEGIN
        PRINT,'CALL_EXTERNAL result was: ',result
        PRINT,'real result is          : ',check
    ENDIF ELSE PRINT,'result is: ',result
END