PRO pgm_info,srcname,pgmname,cam,filt,year,month,day,shr,smin,ssec,ehr $
	    ,emin,esec,eht,vRbg,site,exptime,fullscale $
	    ,annotate=annotate,zoom=zoom
;+
; NAME:
;	PGM_INFO
;	
; PURPOSE:
;       Writes information about a .pgm file into an associated
;       text file.  The .pgm file contains Polar Camera images that
;       have been mapped to PACE geomagnetic coordinates at an
;       assumed height that depends on the emission feature imaged.
;       File name size constraints on DOS platforms prevent the
;       use of descriptive (i.e., long) file names, so the information
;	is saved to another file.
;	
; CATEGORY:
;	
; CALLING SEQUENCE:
;	PGM_INFO, SRCNAME, PGMNAME, CAM, FILT, YEAR, MONTH, DAY, SHR $
;		, SMIN, SSEC, EHR, EMIN, ESEC, EHT, VRBG, SITE $
;		, EXPTIME, FULLSCALE, ANNOTATE = ANNOTATE, ZOOM = ZOOM
;	
; INPUTS:
;       SRCNAME: Full pathname of the file containing the images
;		to be transformed.
;       PGMNAME: Full pathname of the .pgm file to be created by
;		POCAFLIC.PRO.
;	CAM:	Camera number (0/1).
;	FILT:	Filter number (0..4).
;	YEAR:	Year of observation (either 2 or 4 digits).
;	MONTH:	Month number of observation.
;	DAY:	Day number of observation (reckoned by Universal Time).
;	SHR, SMIN, SSEC: Hour, minute, second (UT) of start of first image.
;	EHR, EMIN, ESEC: Hour, minute, second (UT) of start of last image.
;	EHT:	Assumed height of emission (km).
;       VRBG:   Zenith brightness (Rayleighs) of an assumed uniformly-
;               emitting layer whose brightness is subtracted from
;		each image.
;       SITE:   String giving the location of the Polar Camera at
;		the time of the observations.
;       EXPTIME: The exposure time of the images to be stored in
;               the .pgmfile; either 0 (if all available exposure
;               times accepted) or non-zero if only one exposure
;		time accepted.
;       FULLSCALE: The value (in Rayleighs) of the brightness
;               corresponding to the top of the colour table used.
;		Brightnesses greater than this are saturated.
;	
; KEYWORD PARAMETERS:
;       ANNOTATE: True if the mapped images are labelled with date,
;               time, etc., and gridded with PACE geomagnetic
;		coordinate lines.
;       ZOOM:   True if the coordinate grid has been expanded to
;               show greater detail in images mapped to heights
;		less than 300 km.
;
; OUTPUTS:
;	None.
;	
; COMMON BLOCKS:
;	None.
;	
; SIDE EFFECTS:
;	A text file is created, containing the above information.
;
; RESTRICTIONS:
;	None that I can think of.
;
; PROCEDURE:
;	Straightforward.
;
; MODIFICATION HISTORY:
;	Written 94/06/14 by D P Steele.
;-

; Open the file to hold the information about the .pgm file.

pginame=pgmname
STRPUT,pginame,'i',STRLEN(pginame)-1
OPENW,infounit,pginame,/GET_LUN

; Write information about the .pgm file

PRINTF,infounit,'The image source file name is ',srcname
PRINTF,infounit,'The .pgm file name is ',pgmname
PRINTF,infounit,'Created at '+SYSTIME()
PRINTF,infounit,'Images from camera '+STRTRIM(cam,2)+', filter '+STRTRIM(filt,2)
PRINTF,infounit,ymd2date(year,month,day,format='d$ n$ y$')
PRINTF,infounit,'Start with first image after '+strsec(ROUND((shr*60.+smin)*60.+ssec))+' UT'
PRINTF,infounit,'Finish with last image before '+strsec(ROUND((ehr*60.+emin)*60.+esec))+' UT'
PRINTF,infounit,'Assumed emission height '+STRTRIM(eht,2)+' km'
IF vRbg GT 0. THEN BEGIN
    PRINTF,infounit,'Subtracted a uniform emitting layer of ' $
		    +STRTRIM(vRbg,2)+' R brightness'
    PRINTF,infounit,'Layer height '+STRTRIM(eht,2)+' km'
    ENDIF
PRINTF,infounit,'Images acquired at '+site
IF exptime GT 0 $
    THEN PRINTF,infounit,'Image exposure time ',exptime,' s',FORMAT='(A,F4.1,A)' $
    ELSE PRINTF,infounit,'All exposure times accepted (probably 10.0s and 60.0 s)'
IF fullscale GT 0 $
    THEN PRINTF,infounit,'Full scale image brightness',fullscale,' R' $
	       ,FORMAT='(A,F6.0,A)' $
    ELSE PRINTF,infounit,'Each image scaled independently to 99.9th percentile brightness'
IF KEYWORD_SET(annotate) $
    THEN PRINTF,infounit,'Images gridded and labelled'
IF KEYWORD_SET(zoom) $
    THEN PRINTF,infounit,'Coordinates zoomed to maximize resolution'

; Close the file

FREE_LUN,infounit

RETURN
END