;;$Id: incr_struct.pro,v 1.1 1998/10/19 20:51:10 beth Exp $	
;;
;; NAME:
;;
;; 	incr_struct.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>incr_struct
;;      or
;;      IDL>incr_struct,{astructure}
;;
;;      see astructure__define.pro for the structure definition.
;;
;; INPUTS/OUTPUTS:
;;      s_arr - an array of structures of type "astructure". The structure
;;              defintion must match the one given in astructure__define.pro
;;              On return, all of the fields in all of the structures in s_arr
;;              will have been incremented by 1.
;;
;;
;; 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:
;;
;;      It is important that the IDL structure definition
;;      and the C structure definition match exactly.  Otherwise,
;;      there will be no way to prevent this program from
;;      segfaulting or doing other strange things.
;;
;; MODIFICATION HISTORY:
;;	Written May, 1998 JJG
;;
PRO incr_struct,s_arr,DEBUG=debug

    if NOT(KEYWORD_SET(debug)) THEN  ON_ERROR,2
    ;check type of s_arr
    CASE SIZE(s_arr,/TNAME) OF
        'UNDEFINED': s_arr = replicate({astructure},2)
        'STRUCT':  BEGIN
            IF TAG_NAMES(s_arr,/STRUCTURE_NAME) NE 'ASTRUCTURE' THEN $
             MESSAGE,'S_ARR is not the correct structure type'
        END
        ;there's no good way to cast things to type struct.
        ELSE:  MESSAGE,'S_ARR must be a structure'
    ENDCASE

    PRINT,'Calling external routine with:'
    N = N_ELEMENTS(s_arr)
    FOR I=0,N-1 DO BEGIN
        print,form = '(a,i3,a)','s_arr[',i,']'
        HELP,s_arr[i],/STRUCTURE
        PRINT,s_arr[i].four
    ENDFOR
    j = 0l
    IF (CALL_EXTERNAL(lib_name('call_examples'),$
                      'incr_struct',s_arr,n,/PORTABLE)) THEN BEGIN
        PRINT,'After calling external routine:'
        N = N_ELEMENTS(s_arr)
        FOR I=0,N-1 DO BEGIN
            print,form = '(a,i3,a)','s_arr[',i,']'
            HELP,s_arr[i],/STRUCTURE
            PRINT,s_arr[i].four
        ENDFOR
    ENDIF ELSE MESSAGE,'Call to incr_struct failed'
END