;docformat='rst'
;+
; The purpose is to retrieve information from the TelemetryItemDefinition table
;   given a combination of an externalElement and an itemName.
;   
; Author:  Chris Pankratz, Bill Barrett
;
;-
;+
; :Params:
;   externalelement : in, required, type=String
;     The external element string from which the telemetry item
;     originates.
;
;   item_name : in, required, type=String
;     The item name of the telemetry item requested.
;
;   tlmItem_rec: out, required, type=struct
;     The structure described below
;
; :Examples:
;   get_itemname_item_definition, 'ac', , tlmItem_rec
;
;   IDL> get_itemname_item_definition, 'ac', , tlmItem_rec
;   IDL> help, /st, tlmItem_rec
;   ** Structure <6028d0e8>, 10 tags, length=144, data length=136, refs=2:
;   TLMID           LONG              7983
;   EXTERNALELEMENT STRING    'ac'
;   ITEMNAME        STRING    'aqinr2bdyest0'
;   ITEMLENGTH      LONG                64
;   DATATYPE        STRING    'F'
;   FSWDATATYPE     STRING    ''
;   EUUNITS         STRING    'dn'
;   SOURCE          STRING    'AC';      TLMID           LONG            100049
;   DISCUSSION      STRING    null
;-
pro get_itemname_item_definition, externalElement, itemName, tlmItem_rec

  dummy = {cached_itemname_item_definition, query:'', tlmItem_rec:ptr_new() }
  common itemname_item_definition_cache, itemname_item_definitions
  if itemname_item_definitions eq !null then itemname_item_definitions = []

  sql = "select * from AIM_CT_SC.TelemetryItemDefinition where upper(externalElement) = '" + $
    STRUPCASE(STRTRIM(externalElement, 2)) + "' and upper(itemName) = '" + STRUPCASE(STRTRIM(itemName, 2)) + "'"
    
  ; Is there a cached result that can be returned?
  if n_elements(itemname_item_definitions) gt 0 then begin
    idx = where(strlowcase(sql) eq itemname_item_definitions.query, count)
    if count gt 0 then begin
      tlmItem_rec = *itemname_item_definitions[idx[0]].tlmItem_rec
      return
    endif
  endif
  
  ; The code below is used only when there is not a cached result from previous queries
  get_database_login, 'AIM_CT_SC', user=user, password=password, url=url
  ; The purpose of the loop is to allow retries after timeout
  for i = 0, 2 do begin
    query_database, sql, data, nrows, $
      dburl=url, $
      user=user, $
      password=password, /dbconnect
    if nrows gt 0 then break
  endfor

  ; If valid data was returned, cache it.
  ; Otherwise return a flag value indicating no data
  if nrows gt 0 then begin
    ; Define the data structure used for telemetry item records
    tlmItem_rec = replicate({tlm_item_definition, $
      tlmId:0L, externalelement:'', itemName:'', dataType:'', euUnits:'', description:'' }, $
      n_elements(data))
    ; Populate the telemetry item record from the query results
    for i = 0, n_elements(data) - 1 do begin
      tlmItem_rec[i].tlmId = data[i].tlmId
      tlmItem_rec[i].externalelement = data[i].externalelement
      tlmItem_rec[i].itemName = data[i].itemName
      tlmItem_rec[i].dataType = data[i].dataType
      tlmItem_rec[i].euUnits = data[i].euUnits
      tlmItem_rec[i].description = data[i].description
    endfor
    ; Cache the results of this query so that it doesn't need to be repeated
    itemname_item_definitions =  [ itemname_item_definitions, $
      {cached_itemname_item_definition, strlowcase(sql), ptr_new(tlmItem_rec) } ]
  endif else tlmItem_rec = -1

  return
end