: This is a shar archive.  Extract with sh, not csh.
echo x - t_pixutil.x
sed -e 's/^X//' > t_pixutil.x << '!Funky!Stuff!'
X# Copyright(c) 1986 Association of Universities for Research in Astronomy Inc.
X
X# various of the SZ_LINE's should probably be SZ_PATHNAME's...
X
Xinclude	<error.h>
Xinclude	<imhdr.h>
Xinclude	<time.h>
Xinclude <fset.h>
X
X# OIF.H -- IKI/OIF internal definitions.
X
Xdefine	MAX_LENEXTN	3		# max length imagefile extension
Xdefine	OIF_HDREXTN	"imh"		# image header filename extension
Xdefine	OIF_PIXEXTN	"pix"		# image pixfile extension
Xdefine	LEN_PIXHDR	181		# length of PIXHDR structure
Xdefine	COMPRESS	NO		# disable alignment of image lines?
X
Xdefine	HDR		"HDR$"		# stands for header directory
Xdefine	STRLEN_HDR	4
X
Xdefine	SZ_DIMSTR	(IM_MAXDIM*4)
X
X# values for the header access status
Xdefine	NOT_FOUND	0
Xdefine	OK		1
Xdefine	INFERRED	2
Xdefine	WRONG_HEADER	3
X
Xdefine	MAX_BLANKS	SZ_FNAME
X
X
Xtask    pixfix          = t_pixfix,
X        pixheader       = t_pixheader,
X        pixupdate       = t_pixupdate
X
X
X# T_PIXHEADER -- Read contents of a pixel "header" and print on STDOUT.
X
Xprocedure t_pixheader()
X
Xint	list, count, maxlen
Xpointer	sp, pixfile
Xbool	verbose, orphan_only
X
Xint	clpopnu(), clgfil(), max_length()
Xbool	clgetb()
X
Xbegin
X	call smark (sp)
X	call salloc (pixfile, SZ_LINE, TY_CHAR)
X
X	list = clpopnu ("pixels")
X	maxlen = max_length (list)
X
X	verbose = clgetb ("longheader")
X	orphan_only = clgetb ("orphan_only")
X
X	if (clgetb ("left_justify"))
X	    maxlen = -maxlen
X
X	count = 0
X	while (clgfil (list, Memc[pixfile], SZ_LINE) != EOF)
X	    iferr (call pixphdr (Memc[pixfile], verbose, orphan_only,
X		maxlen, count)) {
X
X		call flush (STDOUT)	# to synch the error message
X		call erract (EA_WARN)
X	    }
X
X	call clputi ("nfiles", count)
X
X	call clpcls (list)
X	call sfree (sp)
Xend
X
X
X# PIXPHDR -- Print the contents of a pixel file internal header.
X
Xprocedure pixphdr (pixfile, verbose, orphan_only, maxlen, count)
X
Xchar	pixfile[ARB]		#I pixel file name
Xbool	verbose			#I verbose output?
Xbool	orphan_only		#I only list "orphans"?
Xint	maxlen			#I max length of pixel name for format
Xint	count			#U running count of files listed
X
Xchar	ldim[SZ_DIMSTR], pdim[SZ_DIMSTR], ctime[SZ_TIME]
Xpointer	pix, hdr, sp
Xint	hdr_status
X
Xpointer	pixmap()
Xint	access_hdr()
X
Xerrchk	pixmap, access_hdr, pix_fmt_dim
X
Xbegin
X	pix = pixmap (pixfile)
X
X	call smark (sp)
X	call salloc (hdr, SZ_LINE, TY_CHAR)
X
X	# the header filename is stored in IM_PIXFILE in the pixel file
X	hdr_status = access_hdr (IM_PIXFILE(pix), pixfile, pix,
X	    Memc[hdr], SZ_LINE)
X	if (orphan_only && hdr_status != NOT_FOUND) {
X	    call sfree (sp)
X	    call pixunmap (pix)
X	    return
X	}
X
X	count = count + 1
X	if (verbose && count > 1)
X	    call printf ("\n")
X
X	call printf ("%*s %s %s\n")
X	    call pargi (maxlen)		# L/R justification is implicit
X	    call pargstr (pixfile)
X
X	    switch (hdr_status) {
X	    case NOT_FOUND:
X		call pargstr ("?")
X	    case WRONG_HEADER:
X		call pargstr ("!")
X	    default:
X		call pargstr (" ")
X	    }
X
X	    call pargstr (Memc[hdr])
X
X	if (verbose) {
X	    switch (hdr_status) {
X	    case NOT_FOUND:
X		call print_blanks (abs(maxlen)+3)
X		call printf ("HEADER FILE NOT FOUND\n")
X	    case WRONG_HEADER:
X		call print_blanks (abs(maxlen)+3)
X		call printf ("WRONG HEADER WAS FOUND\n")
X	    case INFERRED:
X		call print_blanks (abs(maxlen)+2)	# line up pathnames
X		call printf ("[%s]\n")
X		    call pargstr (IM_PIXFILE(pix))
X	    }
X
X	    # Format the subscript and date strings
X	    call pix_fmt_dim (pix, ldim, SZ_DIMSTR, IM_LEN(pix,1))
X	    call pix_fmt_dim (pix, pdim, SZ_DIMSTR, IM_PHYSLEN(pix,1))
X	    call cnvtime (IM_CTIME(pix), ctime, SZ_TIME)
X
X	    call print_blanks (abs(maxlen)+3)
X	    call printf ("%s[%s], physdim %s\n")
X		call pargstr (ldim)
X		call ph_pargtype (IM_PIXTYPE(pix))
X		call pargstr (pdim)
X
X	    call print_blanks (abs(maxlen)+3)
X	    call printf ("created %s\n")
X		call pargstr (ctime)
X	}
X
X	call sfree (sp)
X	call pixunmap (pix)
Xend
X
X
X# PIXMAP -- "Map" a pixel file's internal header.  We could play some
X# games with tricking immap to work, but the IM_MAGIC string is
X# hardwired to "imhdr" (instead of "impix") throughout much of the
X# IMIO and the OIF IKI.
X
Xpointer procedure pixmap (pixfile)
X
Xchar	pixfile[ARB]		#I pixel file pathname
X
Xpointer	pix, buf, sp
Xint	fd, n
X
Xint	open(), read()
Xbool	strne()
X
Xerrchk	open, seek, read
X
Xbegin
X	fd = open (pixfile, READ_ONLY, BINARY_FILE)
X
X	call malloc (pix, LEN_IMDES + LEN_PIXHDR, TY_STRUCT)
X
X	iferr {
X	    sp = NULL
X
X	    call seek (fd, BOFL)
X	    n = read (fd, IM_MAGIC(pix), LEN_PIXHDR * SZ_STRUCT)
X
X	    if (n < LEN_PIXHDR * SZ_STRUCT || strne (IM_MAGIC(pix), "impix")) {
X		call smark (sp)		# the stack is freed by the handler
X		call salloc (buf, SZ_LINE, TY_CHAR)
X
X		call sprintf (Memc[buf], SZ_LINE, "Pixel file `%s' unreadable.")
X		    call pargstr (pixfile)
X
X		call error (1, Memc[buf])
X	    }
X	} then {
X	    if (sp != NULL)
X		call sfree (sp)
X	    call close (fd)
X	    call mfree (pix, TY_STRUCT)
X	    call erract (EA_ERROR)
X	}
X
X	call close (fd)
X	return (pix)
Xend
X
X
X# PIXUNMAP -- "Unmap" a pixel file's internal header.
X
Xprocedure pixunmap (pix)
X
Xpointer	pix			#I pixel file descriptor
X
Xbegin
X	if (pix != NULL)
X	    call mfree (pix, TY_STRUCT)
X
X	# just to be sure
X	pix = NULL
Xend
X
X
X# ACCESS_HDR -- Is the indicated header file accessable?  If not, can
X# a better pathname be inferred from the given header directory and the
X# pixel file root name?
X
Xint procedure access_hdr (hdrfile, pixfile, pix, newhdr, maxch)
X
Xchar	hdrfile[ARB]		#I header file pathname to test
Xchar	pixfile[ARB]		#I pixel file for reconstruction
Xpointer	pix			#I pixel descriptor for comparison
Xchar	newhdr[ARB]		#O header pathname if found
Xint	maxch			#I maximum length of newhdr
X
Xpointer	im, hdr, path, root, sp, pix2
Xint	status
Xint	junk
X
Xpointer	immap(), pixmap()
Xint	fnldir(), fnroot()
Xbool	aveqi()
X
Xerrchk	immap, pixmap
X
Xbegin
X	call flush (STDOUT)	# to synch immap KS prompts
X
X	call smark (sp)
X	call salloc (hdr, SZ_LINE, TY_CHAR)
X	call salloc (path, SZ_LINE, TY_CHAR)
X	call salloc (root, SZ_LINE, TY_CHAR)
X
X	# convert VMS style names
X	call hokey_osfn2vfn (hdrfile, Memc[hdr], SZ_LINE)
X
X	# and extract the directory (sometimes needed below)
X	junk = fnldir (Memc[hdr], Memc[path], SZ_LINE)
X
X	ifnoerr (im = immap (Memc[hdr], READ_ONLY, 0)) {
X	    call strcpy (hdrfile, newhdr, maxch)
X	    status = OK
X
X	} else {
X	    # another guess based on the pixel file name
X	    junk = fnroot (pixfile, Memc[root], SZ_LINE)
X	    call strcpy (Memc[path], Memc[hdr], SZ_LINE)
X	    call strcat (Memc[root], Memc[hdr], SZ_LINE)
X
X	    # for neatness - but can fail if oif image lacks an extension
X	    call strcat (".imh", Memc[hdr], SZ_LINE)
X
X	    ifnoerr (im = immap (Memc[hdr], READ_ONLY, 0)) {
X		call strcpy (Memc[hdr], newhdr, maxch)
X		status = INFERRED
X
X	    } else {
X		call sfree (sp)
X		call strcpy (hdrfile, newhdr, maxch)
X		return (NOT_FOUND)
X	    }
X	}
X
X	# the header exists - but is it the right header?
X
X	# make the header's pointer to the pixel file usable
X	call pu_gpixfname (IM_PIXFILE(im), Memc[path], SZ_LINE)
X
X	# compare the new pixel file to the old one
X	pix2 = pixmap (Memc[path])
X
X	# assumes SZ_STRUCT == SZ_INT
X	if (! aveqi (IM_MAGIC(pix), IM_MAGIC(pix2), LEN_PIXHDR))
X	    status = WRONG_HEADER
X
X	call pixunmap (pix2)
X	call imunmap (im)
X	call sfree (sp)
X	return (status)
Xend
X
X
X# HOKEY_OSFN2VFN -- escape the first '[' in a header pathname to get us
X# past immap.  There shouldn't be any conflict with the section notation.
X
Xprocedure hokey_osfn2vfn (osfile, vfile, maxch)
X
Xchar	osfile[ARB]		#I os dependent pathname
Xchar	vfile[ARB]		#O acceptable VOS pathname
Xint	maxch			#I maximum length of vfile
X
Xint	i, stridxs()
X
Xbegin
X	i = stridxs ("[", osfile)
X
X	if (i > 0) {
X	    call strcpy (osfile, vfile, i-1)
X	    call strcpy ("\\", vfile[i], 1)
X	    call strcpy (osfile[i], vfile[i+1], maxch-i)
X	} else
X	    call strcpy (osfile, vfile, maxch)
Xend
X
X
X# PU_GPIXFNAME -- expand an image headers copy of the pathname to
X# the pixel file into an exceptable host/vos pathname.
X
Xprocedure pu_gpixfname (pixpath, realpath, maxch)
X
Xchar	pixpath[ARB]		#I pixel path as known to the header
Xchar	realpath[ARB]		#U header directory [I] / pixel path [O]
Xint	maxch			#I max length of realpath
X
Xint	strsearch()
X
Xbegin
X	if (strsearch (pixpath, "HDR$") == 5)
X	    call strcat (pixpath[5], realpath, maxch)
X	else
X	    call strcpy (pixpath, realpath, maxch)
Xend
X
X
X# MAX_LENGTH -- find the maximum length of a file name from a template.
X# This is coded using clgfil, but the fnt package could be used directly.
X
Xint procedure max_length (list)
X
Xint	list		#I file template descriptor
X
Xint	maxlen
Xpointer	filename, sp
X
Xint	clgfil(), strlen()
X
Xbegin
X	call smark (sp)
X	call salloc (filename, SZ_LINE, TY_CHAR)
X
X	maxlen = 0
X	while (clgfil (list, Memc[filename], SZ_LINE) != EOF)
X	    maxlen = max (strlen (Memc[filename]), maxlen)
X
X	call clprew (list)
X
X	call sfree (sp)
X	return (maxlen)
Xend
X
X
X# PIX_FMT_DIM -- Format the image dimensions in the form
X# of a subscript, i.e., "[nx,ny,nz,...]".
X
Xprocedure pix_fmt_dim (pix, outstr, maxch, len_axes)
X
Xpointer	pix			#I pixel file descriptor
Xchar	outstr[ARB]		#O formatted dimension string
Xint	maxch			#I maximum length of outstr
Xlong	len_axes[ARB]		#I array of axis lengths (for convenience)
X
Xint	i, fd
X
Xint	stropen()
Xerrchk	stropen, fprintf, pargl
X
Xbegin
X	fd = stropen (outstr, maxch, NEW_FILE)
X
X	call fprintf (fd, "[%d")
X	    call pargl (len_axes[1])
X
X	do i = 2, IM_NDIM(pix) {
X	    call fprintf (fd, ",%d")
X		call pargl (len_axes[i])
X	}
X
X	call fprintf (fd, "]")
X	call close (fd)
Xend
X
X
X# PH_PARGTYPE -- Convert an integer type code into a string,
X# and output the string with PARGSTR to FMTIO.
X
Xprocedure ph_pargtype (dtype)
X
Xint	dtype			#I data type code
X
Xbegin
X	switch (dtype) {
X	case TY_UBYTE:
X	    call pargstr ("ubyte")
X	case TY_BOOL:
X	    call pargstr ("bool")
X	case TY_CHAR:
X	    call pargstr ("char")
X	case TY_SHORT:
X	    call pargstr ("short")
X	case TY_USHORT:
X	    call pargstr ("ushort")
X	case TY_INT:
X	    call pargstr ("int")
X	case TY_LONG:
X	    call pargstr ("long")
X	case TY_REAL:
X	    call pargstr ("real")
X	case TY_DOUBLE:
X	    call pargstr ("double")
X	case TY_COMPLEX:
X	    call pargstr ("complex")
X	case TY_POINTER:
X	    call pargstr ("pointer")
X	case TY_STRUCT:
X	    call pargstr ("struct")
X	default:
X	    call pargstr ("unknown datatype")
X	}
Xend
X
X
X# PH_PARGSTAT -- Convert an integer type code into a string,
X# and output the string with PARGSTR to FMTIO.
X
Xprocedure ph_pargstat (dtype)
X
Xint	dtype			#I data type code
X
Xbegin
X	switch (dtype) {
X	case NOT_FOUND:
X	    call pargstr ("[NOT FOUND]")
X	case OK:
X	    call pargstr ("[ok]")
X	case INFERRED:
X	    call pargstr ("[inferred]")
X	default:
X	    call pargstr ("[UNKNOWN]")
X	}
Xend
X
X
X# PRINT_BLANKS -- output a number of blanks on the stdout.  Only need
X# this since the %t and %w formats won't take deferred value fields.
X
Xprocedure print_blanks (number)
X
Xint	number		#I number of blanks to print
X
Xint	i
X
Xbegin
X	do i = 1, min (number, MAX_BLANKS)
X	    call printf (" ")
Xend
X
X
X# T_PIXFIX -- regenerate a header for a wayward pixel file.
X
Xprocedure t_pixfix ()
X
Xint	pixlist, junk
Xpointer	pix, sp, pixfile, hdrfile, path, root
Xbool	firsttime, old_directory, old_name, update
X
Xbool	clgetb()
Xint	clpopnu(), clgfil(), fnldir(), fnroot()
Xpointer	pixmap()
X
Xerrchk	pixmap, pu_init_header
X
Xbegin
X	firsttime = true
X
X	call smark (sp)
X	call salloc (pixfile, SZ_LINE, TY_CHAR)
X	call salloc (hdrfile, SZ_LINE, TY_CHAR)
X	call salloc (path, SZ_LINE, TY_CHAR)
X	call salloc (root, SZ_LINE, TY_CHAR)
X
X	pixlist = clpopnu ("pixels")
X
X	old_directory = clgetb ("old_directory")
X	if (! old_directory) {
X	    call clgstr ("directory", Memc[root], SZ_LINE)
X	    junk = fnldir (Memc[root], Memc[path], SZ_LINE)
X	}
X
X	old_name = clgetb ("old_name")
X	update = clgetb ("update")
X
X	while (clgfil (pixlist, Memc[pixfile], SZ_LINE) != EOF) {
X	    iferr (pix = pixmap (Memc[pixfile])) {
X		call flush (STDOUT)	# to synch the error message
X		call erract (EA_WARN)
X		next
X	    }
X		
X	    if (old_directory)
X		# header name is stored in IM_PIXFILE in the pixel file
X		junk = fnldir (IM_PIXFILE(pix), Memc[hdrfile], SZ_LINE)
X	    else
X		call strcpy (Memc[path], Memc[hdrfile], SZ_LINE)
X
X	    if (old_name)
X		junk = fnroot (IM_PIXFILE(pix), Memc[root], SZ_LINE)
X	    else
X		junk = fnroot (Memc[pixfile], Memc[root], SZ_LINE)
X
X	    call strcat (Memc[root], Memc[hdrfile], SZ_LINE)
X	    call strcat (".imh", Memc[hdrfile], SZ_LINE)	# for neatness
X
X	    iferr (call pu_init_header (Memc[hdrfile], Memc[pixfile], pix)) {
X		call pixunmap (pix)
X		call flush (STDOUT)
X		call erract (EA_WARN)
X		next
X	    }
X
X	    if (update)
X		call pu_update_pix (Memc[hdrfile], Memc[pixfile], pix)
X
X	    if (! firsttime)
X		call printf ("\n")
X
X	    call printf ("Created header `%s'\nfor pixel file `%s'\n")
X		call pargstr (Memc[hdrfile])
X		call pargstr (Memc[pixfile])
X
X	    call pixunmap (pix)
X
X	    firsttime = false
X	}
X
X	call clpcls (pixlist)
X	call sfree (sp)
Xend
X
X
X# PU_INIT_HEADER -- initialize a blank header to point to a pixel file.
X
Xprocedure pu_init_header (hdrfile, pixfile, pix)
X
Xchar	hdrfile[ARB]		#I name of header to create
Xchar	pixfile[ARB]		#I name of pixel file
Xpointer	pix			#I pixel file descriptor
X
Xint	i
Xpointer	sp, pixpath, hdr
X
Xpointer	immap()
Xerrchk	immap
X
Xbegin
X	call smark (sp)
X	call salloc (pixpath, SZ_LINE, TY_CHAR)
X
X	hdr = immap (hdrfile, NEW_IMAGE, 0)
X
X	IM_PIXTYPE(hdr)	= IM_PIXTYPE(pix)
X	IM_NDIM(hdr)	= IM_NDIM(pix)
X
X	do i = 1, IM_MAXDIM {
X	    IM_LEN(hdr,i)	= IM_LEN(pix,i)
X	    IM_PHYSLEN(hdr,i)	= IM_PHYSLEN(pix,i)
X	}
X
X	# some of these aren't needed (some others might be)
X	IM_LUTOFF(hdr)	= IM_LUTOFF(pix)
X	IM_PIXOFF(hdr)	= IM_PIXOFF(pix)
X	IM_HGMOFF(hdr)	= IM_HGMOFF(pix)
X	IM_BLIST(hdr)	= IM_BLIST(pix)
X	IM_SZBLIST(hdr)	= IM_SZBLIST(pix)
X	IM_NBPIX(hdr)	= IM_NBPIX(pix)
X
X	call strcpy ("Reconstructed Header", IM_TITLE(hdr), SZ_IMTITLE)
X
X	call fpathname (pixfile, Memc[pixpath], SZ_LINE)
X	call strcpy (Memc[pixpath], IM_PIXFILE(hdr), SZ_IMPIXFILE)
X
X	call imunmap (hdr)
X	call sfree (sp)
Xend
X
X
X# PU_UPDATE_PIX -- modify the internal pixel file pointer to reference
X# the newly created header file.
X
Xprocedure pu_update_pix (hdrfile, pixfile, pix)
X
Xchar	hdrfile[ARB]		#I pathname to the new header
Xchar	pixfile[ARB]		#I pathname to the pixel file
Xpointer	pix			#I pixel file descriptor
X
Xint	fd
X
Xint	open()
X
Xerrchk	open, seek, write, close
X
Xbegin
X	# header filename is stored in IM_PIXFILE in the pixel header
X	call strcpy (hdrfile, IM_PIXFILE(pix), SZ_IMPIXFILE)
X
X	# only write over the internal header
X	# could limit this to the IM_PIXFILE string itself...
X	fd = open (pixfile, WRITE_ONLY, BINARY_FILE)
X	call seek (fd, BOFL)
X	call fseti (fd, F_BUFSIZE, LEN_PIXHDR * SZ_STRUCT)
X	call write (fd, IM_MAGIC(pix), LEN_PIXHDR * SZ_STRUCT)
X	call close (fd)
Xend
X
X
X# T_PIXUPDATE -- correct the internal pixel file pointers to a
X# list of image headers.
X
Xprocedure t_pixupdate ()
X
Xpointer	hdrlist, hdrpath, hdrfile, hdr, pixfile, pix, sp
Xint	junk
X
Xpointer	imtopenp(), immap(), pixmap()
Xint	imtgetim(), fnldir()
X
Xerrchk	immap, pixmap
X
Xbegin
X	call smark (sp)
X	call salloc (hdrpath, SZ_LINE, TY_CHAR)
X	call salloc (hdrfile, SZ_LINE, TY_CHAR)
X	call salloc (pixfile, SZ_LINE, TY_CHAR)
X
X	hdrlist = imtopenp ("headers")
X
X	while (imtgetim (hdrlist, Memc[hdrfile], SZ_LINE) != EOF) {
X	    iferr (hdr = immap (Memc[hdrfile], READ_ONLY, 0)) {
X		call erract (EA_WARN)
X		next
X	    }
X
X	    junk = fnldir (Memc[hdrfile], Memc[pixfile], SZ_LINE)
X	    call pu_gpixfname (IM_PIXFILE(hdr), Memc[pixfile], SZ_LINE)
X	    call imunmap (hdr)
X
X	    ifnoerr (pix = pixmap (Memc[pixfile])) {
X		call fpathname (Memc[hdrfile], Memc[hdrpath], SZ_LINE)
X		call pu_update_pix (Memc[hdrpath], Memc[pixfile], pix)
X		call pixunmap (pix)
X	    } else
X		call erract (EA_WARN)
X	}
X
X	call imtclose (hdrlist)
X	call sfree (sp)
Xend
!Funky!Stuff!
echo x - pixheader.hlp
sed -e 's/^X//' > pixheader.hlp << '!Funky!Stuff!'
X.help pixheader Jun90 nlocal
X.ih
XNAME
Xpixheader -- list the internal headers of pixel files
X.ih
XUSAGE
Xpixheader pixels
X.ih
XPARAMETERS
X.ls pixels
XList of IRAF pixel files.  The `.pix' suffix must be supplied.
X.le
X.ls longheader = no
XPrint a verbose listing?
X.le
X.ls orphan_only = no
XOnly list those pixel files that appear to be orphaned?  A pixel file
Xmay be orphaned if host system utilities are used to remove the
Xcorresponding header file, or occasionally if a task aborts.
X.le
X.ls left_justify = no
XLeft justify the pixel file names in the output?
X.le
X.ls nfiles [OUTPUT]
XNumber of files that matched the \fIpixels\fR template, subject to the
Xvalue of the \fIorphan_only\fR parameter.
X.le
X.ih
XDESCRIPTION
XPIXHEADER prints the internal pixel file "header" information in
Xvarious formats for the list of IRAF (OIF) pixel files specified by
X\fIpixels\fR. If \fIlongheader\fR = no, the pixel file name and a
Xpointer to the corresponding image header are printed.  If
X\fIlongheader\fR = yes, the image dimensions, the data type, the
Xphysical storage dimensions, and the original creation time are also
Xprinted.  If \fIorphan_only\fR = yes, only the apparently orphaned
Xpixel files will be listed.
X
XOrphaned pixel files, i.e., those without an apparent corresponding
Xheader file, are flagged in the output with a question mark, `?',
Xbetween the pixel and header pathnames.  Pixel files that have a
Xpointer to an existing but \fIincorrect\fR header are flagged with an
Xexclamation point, `!'.
X
XThe header parameters internal to the pixel file are \fBnot\fR
Xguaranteed to be up-to-date since the pixel file header information
Xis only written when the file is created, and the pixel file is not
Xupdated every time the image header file is updated.  An image that has
Xbeen imrenamed or that has been processed in various ways may no
Xlonger have the correct header file name written in the pixel file.
XThe task does attempt to track down the current name of the header
Xfile using the name of the pixel file and the directory listed internal
Xto the pixel file, but this is not fool-proof.  If \fIlongheader\fR = yes,
Xsuccessfully inferred header file names are flagged in the output with the
Xoriginal header pathname from the pixel file, in brackets.
X
XWhile the task may fail to find some valid headers, it should not
Xreport a valid header where there is none, since the header's copy of
Xthe pathname to the pixel file is used to double-check the identity of
Xthe actual pixel file by reading the internal header a second time.
X
XNote that the `HDR$' syntax is handled correctly.
X.ih
XEXAMPLES
XPrint the internal headers of a list of IRAF pixel files:
X
X    lo> pixheader *.pix
X
XPrint verbose information from the pixel file headers:
X
X    lo> pixheader *.pix lo+
X
XList only the orphaned pixel files, and count them:
X
X.nf
X    lo> pixheader *.pix orphan+
X    lo> = pixh.nfiles
X.fi
X
XNote that the list of orphaned pixel files may include some files that
X\fImerely have out-of-date references\fR to the header file pathnames
Xand have thus become "detached" from the header files.
X.ih
XBUGS
XThe VOS should keep the internal pixel pointer to the header up-to-date.
X
XThe task will not locate the header for a pixel file which had an
Xextension appended by the VOS in order to avoid
Xa name collision, if the header was subsequently renamed.
X
XIf the task locates the wrong header for a pixel file, no attempt is
Xmade to locate another header.
X.ih
XSEE ALSO
Xpixfix, pixupdate, imheader
X.endhelp
!Funky!Stuff!
echo x - pixheader.par
sed -e 's/^X//' > pixheader.par << '!Funky!Stuff!'
Xpixels,s,a,,,,Pixel file names
Xlongheader,b,h,no,,,Print the pixel header in multi-line format?
Xorphan_only,b,h,no,,,Only list orphaned pixel files?
Xleft_justify,b,h,no,,,Left justify the pixel file names?
Xnfiles,i,h,,,,Number of pixel files in the output list
!Funky!Stuff!
echo x - pixfix.hlp
sed -e 's/^X//' > pixfix.hlp << '!Funky!Stuff!'
X.help pixfix Jun90 nlocal
X.ih
XNAME
Xpixfix -- resurrect an image header for an orphaned pixel file
X.ih
XUSAGE
Xpixfix pixels
X.ih
XPARAMETERS
X.ls pixels
XThe list of pixel files (including the ".pix") whose headers are to be
Xresurrected.
X.le
X.ls directory = ""
XThe directory in which to place the new headers.  This is ignored if
X\fIold_directory\fR = yes.  The default value of the NULL string ("")
Xmeans the current directory.
X.le
X.ls old_name = no
XRestore the original header filenames?  If \fIold_name\fR = yes, the
Xheader file names from the internal pixel headers will be used for the
Xnewly created headers.  If \fIold_name\fR = no, the new headers will
Xhave the same root name as the pixel file.
X.le
X.ls old_directory = no
XRestore the headers to the original directories?  If \fIold_directory\fR
X= yes, the newly created headers will be placed in the directory
Xspecified in the internal pixel file header.  If \fIold_directory\fR =
Xno, the new headers will be placed in the directory specified by the
X\fIdirectory\fR parameter.
X.le
X.ls update = no
XUpdate the new header pathnames in the pixel files?  If \fIupdate\fR =
Xyes, the internal pixel file pointer to the header file will be updated
Xto agree with the new header.  If \fIupdate\fR = no (the suggested
Xchoice), the pixel file will remain untouched.
X.le
X.ih
XDESCRIPTION
XPIXFIX can be used to recreate functional image headers for orphaned
Xpixel files.  The new headers will contain only the bare minimum
Xinformation about the images since, of course, most of the header
Xinformation is contained in the image header file.  This task is only
Xof use with OIF (Old or Original Image Format) IRAF images, i.e.,
X"normal" IRAF images.
X.ih
XEXAMPLES
XTo recreate headers in the current directory from a list of pixel files:
X
X    lo> pixfix @orphan
X
XTo recreate the headers in the original directories, with the original
Xnames:
X
X    lo> pixfix @orphan old_name+ old_dir+
X
XNote that originally, the headers may have been created in the "tmp$"
Xtemporary directory, with some meaningless temporary (but unique)
Xfilename.
X
XTo list and resurrect (in a specified remote directory) potentially
Xorphaned images:
X
X.nf
X    cl> proto
X    pr> nlocal
X    lo> cd imdir
X    lo> pixheader *.pix orphan+ | fields "" 1 > orphan
X    lo> pixfix @orphan directory=home$test/
X.fi
X.ih
XBUGS
XNone known, but the update option should not be selected under normal
Xconditions.  The internal pixel file header is updated using a
Xtechnique that violates the IMIO programming interface.
X.ih
XSEE ALSO
Xpixheader, pixupdate
X.endhelp
!Funky!Stuff!
echo x - pixfix.par
sed -e 's/^X//' > pixfix.par << '!Funky!Stuff!'
Xpixels,s,a,,,,Pixel file names
Xdirectory,s,h,"",,,Directory for new headers
Xold_name,b,h,no,,,Restore the original header filenames?
Xold_directory,b,h,no,,,Restore the headers to the original directories?
Xupdate,b,h,no,,,Update the new header pathnames in the pixel files?
!Funky!Stuff!
echo x - pixupdate.hlp
sed -e 's/^X//' > pixupdate.hlp << '!Funky!Stuff!'
X.help pixupdate Jun90 nlocal
X.ih
XNAME
Xpixupdate -- fix pixel files' back pointers for a list of headers
X.ih
XUSAGE
Xpixupdate headers
X.ih
XPARAMETERS
X.ls headers
XThe list of image headers whose pixel files' backward header pointers
Xare to be updated.
X.le
X.ih
XDESCRIPTION
XPIXUPDATE will update internal pixel file headers that are out-of-date
Xwith respect to the corresponding header files.  This task is only of
Xuse with OIF (Old or Original Image Format) IRAF images, i.e.,
X"normal" IRAF images.
X
XThe problem that the task is a partial solution for is that the
Xinternal pixel header for an image is never updated after the image is
Xcreated.  This is in obvious contrast to the actual image header file
Xwhich is always kept up-to-date.  After a sequence of image
Xmanipulations (e.g., using IMRENAME or any task which uses intermediate
Xtemporary images), the pixel file copy of the backwards pointer to the
Xheader file may no longer be valid.
X
XThese out-of-date header pointers are mainly of concern for system
Xhousekeeping duties, because it is necessary to keep track of (and
Xdelete or resurrect using PIXFIX) "orphaned" pixel files whose headers
Xhave been deleted improperly.
X.ih
XEXAMPLES
XYou may use the PIXHEADER task to compile an initial list of possibly
Xorphaned pixel files, for instance in a user's "imdir" data directory.
XPIXUPDATE can then be used (from the directories where the image
Xheaders are located) to clean up any of the (somehow) identified
Xspurious orphans.  This iterative use of the tools can narrow in on a
Xlist of actual pixel file orphans that may be deleted or resurrected
X(using PIXFIX).
X
XTo update the pixel files for a list of image headers:
X
X    lo> pixupdate wayward*.imh
X.ih
XBUGS
XNone known, but \fIthis task should NOT be used\fR with normal, day-to-day
Ximage reductions.  The internal pixel file header is updated using a
Xtechnique that violates the IMIO programming interface.
X.ih
XSEE ALSO
Xpixheader, pixfix
X.endhelp
!Funky!Stuff!
echo x - pixupdate.par
sed -e 's/^X//' > pixupdate.par << '!Funky!Stuff!'
Xheaders,s,a,,,,List of headers
!Funky!Stuff!
echo x - orphan.cl
sed -e 's/^X//' > orphan.cl << '!Funky!Stuff!'
Xprocedure orphan (images)
X
Xstring	images		{prompt="Image list"}
Xbool	stop	= no	{prompt="List the NON-orphaned image headers?"}
Xint	number		{prompt="OUTPUT:  Number of orphans found"}
X
Xstruct	*list
X
Xbegin
X	int	count = 0
X	string	l_images, hdr, pix, tmp
X	bool	pix_is_there
X
X	tmp = mktemp ("tmp$junk.")
X
X	l_images = images
X	hselect (l_images, "$I,i_pixfile", yes, > tmp)
X
X	list = tmp
X	while (fscan (list, hdr, pix) != EOF) {
X	    if (substr (pix, 1, 4) == "HDR$")
X		pix = substr (pix, 5, strlen (pix))
X
X	    pix_is_there = access (pix)
X
X	    if (pix_is_there == stop)
X		print (hdr)
X
X	    if (! pix_is_there)
X		count += 1
X
X	}
X
X	list=""
X	delete (tmp, ver-, >& "dev$null")
X
X	number = count
Xend
!Funky!Stuff!
echo x - orphan.hlp
sed -e 's/^X//' > orphan.hlp << '!Funky!Stuff!'
X.help orphan Jun90 local
X.ih
XNAME
Xorphan -- list images that have no pixel files
X.ih
XUSAGE
Xorphan images
X.ih
XPARAMETERS
X.ls images
XThe list of image headers that are to be checked for valid pixel file
Xpointers.
X.le
X.ls stop = no
XStop, rather than list, the orphaned headers?  If \fIstop\fR = yes,
Xonly those image headers which (apparently) have pixel files will be
Xlisted.  If \fIstop\fR = no (the default), the list of orphaned image
Xheaders will be printed.
X.le
X.ls number [OUTPUT]
XOn output, the number of orphaned image headers that were detected in
Xthe input list of \fIimages\fR.  This number does not depend on the
Xsetting of the \fIstop\fR parameter.
X.le
X.ih
XDESCRIPTION
XORPHAN checks a list of image headers for the presence of valid pixel
Xfiles.  If \fIstop\fR = no (the default), the orphaned subset of the
Ximage header list is printed out on the STDOUT.  If \fIstop\fR = yes,
Xonly the subset of the image headers that apparently have valid pixel
Xfiles will be listed.  After the task finishes, the \fInumber\fR
Xparameter will contain the number of orphaned image headers that were
Xactually detected.  This number does \fInot\fR depend on the setting of
Xthe \fIstop\fR parameter.
X
XThe "HDR$" syntax is handled properly.
X.ih
XEXAMPLES
XTo check the image headers in the current directory, writing the names
Xof any orphaned headers into the file "orphan_list":
X
X    lo> orphan *.imh > orphan_list
X
XTo clean up the previously listed set of orphaned headers, being
Xprompted before each header is deleted:
X
X    lo> imdelete @orphan_list verify+
X
XPlease double check any list such as this before deleting any data.
XWhile the orphan task is simple and is thought to function correctly,
Xit's a lot easier to check the list \fIbefore\fR deleting the files,
Xrather than to recover the data after erroneously deleting them.
X.ih
XSEE ALSO
Ximheader, hselect, pixheader
X.endhelp
!Funky!Stuff!
exit