;+
; <FUNCTION QUERY_GRIB_FILE>
; The QUERY_GRIB_FILE routine reads the metadata contents of a Gridded Binary (GRIB) file and
;  returns the metadata in an IDL structure variable. The specific information returned is dependant on
;  the keyword FULL. (see Keyword below)
;
; @Param
;   filename {in} {required} {type=string} {default=none}
;     A scalar string specifying the full pathname of the GRIB file to read
;
; @Param
;   info {out} {required} {type=structure} {default=none}
;     An IDL structure that contains the metadata information for each record
;
; @Keyword
;   full {in} {optional} {type=integer} {default=0}
;     Set this keyword to indicate that the routine should return the full metadata structure for every record in the GRIB file.
;     The default is to return a metadata structure with only a few identifying elements for each record in the file. Generally
;     this would be used to query and search for specific types of data in the file without having to read in the very large
;     metadata structure for every record.
;
; @Author
;	Andy Pursch
;	ITT Visual Information Solutions
;
; @Copyright
;   ITT-VIS 2006
;
; @Categories
;   File I/O
;
; @History
;   Original June 2006
;
; @Returns
;   status = 1 for successful query
;   status = -1 for unsuccessful query
;
; @Requires
;  IDL 6.2
;
; @Restrictions
;    Requires idl_grib.dll, idl_grib.dlm
;
; @Version
;   1.0
;-
FUNCTION QUERY_GRIB_FILE, filename, info, full=full
; Define value for error code
status = -1
; Since we are only doing a query on the file to determine its contents
; all we need to do is extract the header records.
pData = READ_GRIB(fname, /header)

; If this is not a valid GRIB file then return error status. A valid file should return
; a pointer to an array of pointers. The type code for an IDL pointer is 10.
IF SIZE(pdata,/type) NE 10 THEN BEGIN
	B = DIALOG_MESSAGE('Invalid GRIB file', /error)
	RETURN, status
ENDIF

; Determine how many records/parameters are contained in this file
sz=SIZE(pData)
PRINT,'Number of Parameters in File: ', sz[1]
nparams = sz[1]

; Create the info structure that will return the descriptive info
; that is contained in the header records. If the keyword FULL is set
; then we return all info for each record. If it is not set just return the
; parameter name/quantity, its description, the grid ID and the level.
IF KEYWORD_SET(full) THEN $
	info = REPLICATE({info:(*pData[0]).info, projection:(*pData[0]).projection}, nparams) $
ELSE info = REPLICATE({quantity:'', description:'', gridid:'', levels:lonarr(2)}, nparams)

; For each record
FOR i=0, nparams-1 DO BEGIN
	IF KEYWORD_SET(full) THEN BEGIN
		; Return the complete header structure for every record in the file
		info[i].info = (*pData[i]).info
		info[i].projection = (*pData[i]).projection
	ENDIF ELSE BEGIN
		; This will return only a few identifying pieces of information for each record. This
		; is generally used to identify and locate specific records and then it is intended
		; for the user to use QUERY_GRIB_RECORD to get the details of the individual
		; parameter/record.
	    info[i].quantity =  (*pData[i]).info.quantity
	    info[i].description = (*pData[i]).info.description
	    info[i].gridid = (*pData[i]).info.gridid
	    info[i].levels = (*pData[i]).info.levels
   	ENDELSE
ENDFOR

; Clean up the pointers before returning
HEAP_FREE, pData, /ptr

status=1
RETURN, status

END