;+
; NAME:
;	readnsosc
; PURPOSE:
;	Read SOLIS files from NSO/Kit Peak
; CALLING SEQUENCE:
	FUNCTION readnsosc, nsofile	, $
		nlng		= nlng		, $
		cvariable	= cvariable	, $
		header		= header	, $
		badfile		= badfile
; INPUTS:
;	nsofile			scalar; type: string
;					fully-qualified name of SOLIS file
; OPTIONAL INPUTS:
;	nlng = nlng		scalar; type: integer; default: 72
; OUTPUTS:
;	results			array with magnetic field values
; OPTIONAL OUTPUTS:
;	cvariable=cvariable
;					array of Carrington variables corresponding
;					to longitude values in source surface array.
; INCLUDE:
	@compile_opt.pro 			; On error, return to caller
; PROCEDURE:
;	The SOLIS files typically contain a 360 x 180 array
;	with radial magnetic field on a grid of equal steps in
;	longitude and sine(latitude).
;
;	The Carrington variable associated with the longitudes
;	is either derived from the filename (old SOLIS files),
;	or the time of the last magnetogram used to construct the
;	map (extracted from the Fits header).
;
;	The input value nlng sets the resolution of the source
;	surface map produced. By default this is 72 (i.e. a
;	resolution of 5 degree). This value is used to set the
;	output array cvariable, which give the Carrington variables
;	for the nlng longitudes in the source surface map.
; MODIFICATION HISTORY:
;	MAY-2013, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
;		Added some documentation.
;-

wsc = readfits(nsofile, hdr,/silent)
IF n_elements(wsc) EQ 1 AND wsc[0] EQ -1 THEN BEGIN
	badfile = 1
	RETURN, wsc[0]
ENDIF
badfile = 0

name = GetFileSpec(nsofile,part='name')

IF strmid(name,0,5) eq 'kcv7g' THEN BEGIN

	; MAPDATE = 130703
	; MAPTIME = 1628
	; MAPNAME = 2138_003

	tmp = TimeSet( '20'+strcompress(fxpar(hdr,'MAPDATE'),/rem)+' '+strcompress(fxpar(hdr,'MAPTIME'),/rem), format='YYYYMNDD hhmm' )
	header = ['OBSERVAT=NSO/KP-SOLIS/VSM', 'OBSTIME='+TimeString(tmp,/_ydoy,upto=TimeUnit(/sec))]

	tmp = fxpar(hdr,'MAPNAME')	; nnnn_lng (carr var with longitude)

ENDIF ELSE IF strmid(name,0,5) eq 'mrbqs' THEN BEGIN

	; MAPDATE = 2016-01-01
	; MAPTIME = 05:04 
	; MAPNAME = 2172_212

	tmp = TimeSet( strcompress(fxpar(hdr,'MAPDATE'),/rem)+' '+strcompress(fxpar(hdr,'MAPTIME'),/rem), format='YYYY-MN-DD hh:mm' )
	header = ['OBSERVAT=NSO/GONG', 'OBSTIME='+TimeString(tmp,/_ydoy,upto=TimeUnit(/sec))]

	tmp = fxpar(hdr,'MAPNAME')	; nnnn_lng (carr var with longitude)


ENDIF ELSE BEGIN

	n = fxpar(hdr,'NFILETOT')

	IF !err NE -1 THEN BEGIN	; New SOLIS file

		; The SOLIS files contain a list of magnetograms used to make the map.
		; The time encoded in the file name for the last magnetogram is
		; the time assigned to the synoptic map.

		tmp = fxpar(hdr,'FILE'+string(format='(I2.2)',n))
		tmp = GetFileSpec(tmp,part='name')
		fmt = 'YYYYMNDD_hhmm'
		tmp = TimeSet(strmid(tmp,strlen(tmp)-strlen(fmt)),format=fmt)
		header = ['OBSERVAT=NSO/KP-SOLIS/VSM (legacy)', 'OBSTIME='+TimeString(tmp,/_ydoy,upto=TimeUnit(/sec))]

		tmp = GetFileSpec(nsofile,part='name')
		tmp = strmid(tmp,strpos(tmp,'_cr'))

	ENDIF ELSE BEGIN

		tmp = GetFileSpec(nsofile,part='name')

		CASE strlowcase( strmid(tmp,0,3) ) OF

		'nso': BEGIN

			; Most of the old SOLIS files have an OBSTIME keyword in it.

			header = 'OBSERVAT=NSO/KP-SOLIS/VSM (old)'
			tmp = fxpar(hdr,'OBSTIME')
			IF !err NE -1 THEN header = [header, 'OBSTIME='+tmp]

		END

		'mdi': header = 'OBSERVAT=SOHO/MDI'

		ELSE : header = 'OBSERVAT=UNKNOWN'

		ENDCASE

		tmp = GetFileSpec(nsofile,part='name')

	ENDELSE

ENDELSE

tmp = flt_string(tmp, /double)

; The Carrington variable grid for the output file has a
; resolution of 5 degrees. The grid is monotonically decreasing from
; the value implied by the file name (CR and longitude) back to
; the previous rotation in steps of 5 degrees.

; Dropping the last element in the Carrington array reduces the
; number of elements from 73 to 72 (this is equivalent to the 
; /dropfirst keyword on wso_read).

CASE n_elements(tmp) EQ 1 OF
0: tmp = tmp[0]+(1-tmp[1]/360)
1: tmp = tmp[0]
ENDCASE

InitVar, nlng, 72
cvariable = tmp-(gridgen(nlng+1,range=double([0,1])))[0:nlng-1]

RETURN, wsc  &  END