DISK_IO

• AIPSDIR
• AIPSNAME
• AIPSRD
• DST_INFO
• IRAFRD
• IRAFWRT
• MID_RD_DISDSC
• MID_RD_IMAGE
• MID_RD_TABLE
• MID_UP_IMAGE
• MID_UP_TABLE
• READ_DST

Routine Descriptions

 NAME:
	AIPSDIR
 PURPOSE:
	Print a listing of AIPS image files on a VAX directory

 CALLING SEQUENCE:
	aipsdir, [ usernum, dir ]

 OPTIONAL INPUTS:
	usernum - an AIPS user number, integer scalar.  AIPDIR will
		only display images belonging to this user.  If not
		supplied or set = -1, then AIPSDIR displays all images 
		on the directory.
	dir - string giving name of the directory containing the AIPS
		catalog.  If not supplied, then the default AIPS directory
		(currently CHAMP$USER5:[AIPS.DATA]) is used

 NOTES:
	Finding the VAX directory that contains your AIPS images appears to
	be as much of an art as a science.  Users on non-LASP systems will have
	to modify line 1 of this program giving the default AIPS directory.

 SIDE EFFECTS:
	AIPSDIR display the user number, slot number, date image was catalogued,
	image name, and VAX directory name.

 METHOD:
	The catalog directory ('CA') files are opened, and interpreted as per
	GOING AIPS (15-APR-1987), p. 5-3

 REVISION HISTORY:
	Written W. Landsman               March, 1986

(See /usr/local/idl/lib/zastron/disk_io/aipsdir.pro)

 NAME
	AIPSNAME
 PURPOSE:
	Returns the VAX filename of a specified AIPS sequence number, for
	a given user number.  Needed because AIPS tries to hide the VAX
	file name, which is what the IDL procedure AIPSRD needs to read an image.

 CALLING SEQUENCE:
	filename = aipsname( userno, [ seqno, directory ] )
 INPUTS:
	userno - AIPS user number, integer scalar
	seqno -  sequence or slot number of image in the user's catalog.
		If not supplied, AIPSNAME will display all images in the
		users catalog, and prompt for a choice.
	directory - string giving disk and directory name to search for the
		image.   If not supplied, AIPSNAME uses the default
		AIPS directory (currently CHAMP$USER5:[AIPS.DATA])

 OUTPUT:
	STRING giving full VAX file name of the catalog header ('CB' file)
	of the desired image.
 EXAMPLE:
	User number 11 wants the VAX filename of the image with a slot
	number of 1 in his catalog.
	FILENAME= AIPSNAME(11,1)

 NOTES:
	AIPSNAME currently assumes an AIPS format version of 'B', i.e.
	for images written in the 15-JAN-1987 AIPS version.  Users
	may need to change the first line of this program for other
	AIPS data formats.  The default AIPS directory also needs to be
	changed on other systems.

	AIPSNAME does not check that the filename really exists;  it merely
	creates a VAX filename from a user number and slot number, as per
	GOING AIPS (15-APR-1987), p. 5-3.

 REVISION HISTORY:
	Written    W. Landsman          March 6, 1989

(See /usr/local/idl/lib/zastron/disk_io/aipsname.pro)

 NAME
	AIPSRD
 PURPOSE:
	Read an AIP disk image (MAP) file into an IDL image and header arrays
	Use AIPSDIR or AIPSNAME to determine the VAX filename of the desired
	AIPS image.

 CALLLING SEQUENCE:
	AIPSRD, im, hdr, [ filename ]   

 OPTIONAL INPUT:
	FILENAME - String giving the complete VAX file name (including 
		extension) of the AIPS image header file.  The first two 
		characters of the file name should be 'CB' and the last two 
		should be '01'.   If a directory is not supplied then AIPSRD 
		uses a default directory (currently 'CHAMP$USER5:[AIPS.DATA]')

 OUTPUTS:
	IM - image array with size and dimensions as specified in the AIPS
		catalog header
	HDR - FITS type header array created from values in the AIPS catalog
		header.  HDR will NOT include any HISTORY keywords.

 REVISION HISTORY:
	Written     W. Landsman              March 7, 1989 

(See /usr/local/idl/lib/zastron/disk_io/aipsrd.pro)

 NAME:
	DST_INFO
 PURPOSE:  
	To read in the next section of the header in a DAOPHOT image file.

 CALLING SEQUENCE:
	PRO DST_INFO, PT, IPT, LPT, BHDR, IHDR, LHDR, FHDR,NAME, VALUE, 
				DIMS, STYPE, TYPE

 PARAMETERS:  
	From what I can gather the PT variables are positions in the
	HDR variables which hold the header data.  The `B' prefix (BPT, BHDR), 
	indicates the variables are in BYTE type, and `I', `L', `F' indicate 
	INTEGER, LONG, and FLOATING respectively.
		pt  +  9        size of object name (1 - 15)
		pt  + 10 - 24   string of object name
		pt  + 25        type of object
		pt  + 26 - 40   string of type      
		pt  + 61...     value(s) of byte object (+4 for each)
		pt  + 64...     string for char object
		ipt + 31...     value(s) of short or int  object (+2 for each)
		lpt +  1        size of object description (data added at end)
		lpt +  2        pointer back to start of structure (4 byte groups)
				always less than or equal to 0
		lpt + 12        pointer to start of next object (4 byte groups)
		lpt + 13        number data values in this object
		lpt + 16...     value(s) of long, int, or float  object 
				or size of string for char object
	The NAME parameter is the name of the header field and VALUE is its 
		value.
  NOTES:  
	See notes for READ_DST procedure.
  PROCEDURE:  
	This procedure dissects the header information passed to it
	in the HDR parameters.  Most of it is done by black magic.

   REVISION HISTORY:  
	03 AUG 87  Written by Michael E. Van Steenberg
	17 OCT 89 toyed with by Joel Parker (cleaned and added comment
			& prolog)
	25 MAY 90 Strtrim added to make it work in IDL version 2.  Should be
		still compatible with IDL version 1.  Robert S. Hill

(See /usr/local/idl/lib/zastron/disk_io/dst_info.pro)

 NAME:
	IRAFRD
 PURPOSE:
	Read an IRAF (OIF) file and read into an IDL image and header arrays.
	Program will prompt for the file name if not supplied.

 CALLING SEQUENCE:
	IRAFRD, im, hdr, filename, [SILENT = , VMSIMG = ]  

 OPTIONAL INPUT:
	FILENAME -  Character string giving the name of the IRAF image 
		header.  If omitted, then program will prompt for the 
		file name.  IRAFRD always assumes the header file has an 
		extension '.imh'.    IRAFRD will automatically locate the
		".pix" file containing the data by parsing the contents of 
		the .imh file.   (If the parse is unsuccesful, then IRAFRD looks
		in the same directory as the .imh file.)
 OUTPUTS:
	IM - array containing image data
	HDR - string array containing header.  Basic information in the
		IRAF header is converted to a FITS style header

 OPTIONAL INPUT KEYWORDS:
	VMSIMG     - UNIX keyword included to indicate that the file
		originated on a VAX.  If VMSIMG ne 0, then byteordering
		appropriate to a vms image will be performed.
	SILENT  - If this keyword is present, the size of the image
		will not be printed.

 SIDE EFFECTS:
	IF FILENAME is not supplied, then the program will check that
	the image and header variable do not already contain data.

 RESTRICTIONS:
	(1)  Image size and history sections of the IRAF header are copied 
		into the FITS header HDR.  Other information (e.g. astrometry)
		might not be included unless it is also in the history section
	(2)  IRAFRD ignores the node name when deciphering the name of the
		IRAF ".pix" file.
	(3)  Certain FITS keywords ( DATATYPE, IRAFNAME) may appear more than
		once in the output name

 PROCEDURE:
	IRAFRD obtains dimensions and type of image from the IRAF header.

 MODIFICATION HISTORY:
	Written W. Landsman, STX January 1989
	Converted to IDL Version 2.  M. Greason, STX, June 1990
	Updated for DecStation compatibility   W. Landsman   March 1992
	Don't leave an open LUN  W. Landsman   July 1993

(See /usr/local/idl/lib/zastron/disk_io/irafrd.pro)

 NAME:
	IRAFWRT
 PURPOSE:
	Write IDL data in IRAF (OIF) format (.imh and .pix files).
	Does the reverse of IRAFRD.

 CALLING SEQUENCE: 
	IRAFWRT, image, hdr, filename, [ PIXDIR = ]

 INPUTS:
	image - array containing data
	hdr   - The  corresponding FITS header.   Use MKHDR to create a minimal
		FITS header if one does not already exist.
	filename - Scalar string giving the name of the file to be written 
		Should not include the extension name, which will be supplied 
		by IRAFWRT.
 OUTPUTS:
	None

 OPTIONAL KEYWORD INPUT:
	PIXDIR - scalar string specifying the directory into which to write
		the IRAF pixel (.pix) file.   The default is to write the pixel
		file to the same directory as the header (.imh) file

 SIDE EFFECTS:
	Image array and  FITS header are written to IRAF pixel file 
		'filename'.pix and header file 'filename'.imh

 EXAMPLE:
	Write an empty 50 x 50 array of all zeros to an IRAF file named 'EMPTY'

	IDL> im = intarr( 50, 50)         ;Create empty array
	IDL> mkhdr, hdr, im               ;Create a minimal FITS header
	IDL> irafwrt, im, hdr, 'empty'    ;Write to a IRAF file named 'empty'

 PROCEDURE:
	IRAFWRT gets information about the data - image dimensions, size, 
	datatype, maximum and minimum pixel values - and writes it into
	the binary part of the header. The ASCII part of the header
	is directly copied after deleting records with certain keywords 
	A pixel file is created, with a header in the first 1024 bytes

 RESTRICTIONS:
	(1) The files are not created by IRAFWRT are not identical to those 
		created by the IRAF routine rfits.    However, the files 
		created by IRAFWRT appear to be compatible with all the IRAF 
		routines tested so far.
	(2)  IRAFWRT has been tested on a limited number of data types
	(3)  IRAFWRT has not been tested on a DecStation.

 MODIFICATION HISTORY:
     Written K. Venkatakrishna, STX February 1992
     VMS compatibility    W. Landsman      April 1992
     Work with headers without DATE-OBS or ORIGIN           August 1992

(See /usr/local/idl/lib/zastron/disk_io/irafwrt.pro)

 NAME:
	MID_RD_DISDSC
 PURPOSE:
	Get a MIDAS directory descriptor from a MIDAS BDF. Note: PORTABLE MIDAS.

 CALLING SEQUENCE:
	MID_RD_DIRDSC,IMAGE,DSCNAME,DSCVALUE

 INPUTS:
	IMAGE = Filename or Logical Unit Number.
		* If a filename is given, the file will be opened and closed 
		using a local LUN.  The filename is that of the MIDAS image, 
		without extension (.BDF will is assumed) or version number 
		(latest version is assumed).
		* If a LUN is given, the file associated with that LUN will be
		 used.
	DSCNAME = Name of the Descriptor wanted.

 OUTPUTS:
	DSCVALUE = Value of the directory descriptor wanted.

 ALGORITHM:
	0) Check inputs and set error handling.
	1) Open file for access using the access method indicated by the type of
		the input parameter IMAGE.
	2) Find the descriptor by name (string type).
	3) Decode the 30 byte descriptor block.
	4) Use #3 to find descriptor data area.
	5) Convert descriptor data as indicated by descriptor block information.
	6) Terminate file access as is proper for the type of parameter IMAGE.

 RESTRICTIONS:
	   1) There must be only one FCB and it must be in VBN 1.
	2) The LDBs must begin in VBN 2.
	3) All descriptors must be in the first LDB.
	4) Note: .bdf and .tbl extensions assumed lower case.

 AUTHORS:
   SAV  - Stephen A. Voels, USM/DAN

 MODIFICATION HISTORY:
	FEB 1989 SAV  Initial programming.
	MAY 1989 FM   Change of name of routine; some minor alterations.
	AUG 1990 FM   Updates for Portable MIDAS (noted as comments below).
	FEB 1991 FM   Conversion to V. 2 of IDL, Unix.

(See /usr/local/idl/lib/zastron/disk_io/mid_rd_dirdsc.pro)

 NAME:
	MID_RD_IMAGE

 PURPOSE:
	Get a pixel matrix and some support information from a MIDAS file.

 CALLING SEQUENCE:
	MID_RD_IMAGE,IMAGE,DATA,NAXIS,NPIX

INPUTS:
	IMAGE = Filename or Logical Unit Number.
	* If a filename is given, the file will be opened and closed using a
		local LUN.  The filename is that of the MIDAS image, without
		extension (.BDF will is assumed) or version number (latest 
		version is assumed).
	* If a LUN is given, the file associated with that LUN will be used.

 OUTPUTS:
	NAXIS = Number of dimensions in MIDAS image. I*4 values.
	NPIX  = Array containing the dimensions. I*4 values.
	DATA  = Array containing the MIDAS image. Dimensions are defined by
		NAXIS and NPIX. R*4 values.

 ALGORITHM:
	0) Check inputs and set error handling.
	1) Open file for access using the access method indicated by the type of
	the input parameter IMAGE.
	2) Get the descriptors of the IMAGE.
		a) NAXIS set the output parameter NAXIS to this value.
		b) NPIX  set the output parameter NPIX to this value.
	3) Locate the pixel data start block
	4) Load pixel data into output parameter DATA
	5) Terminate file access as is proper for the type of parameter IMAGE.

 RESTRICTIONS:
	1) There must be only one FCB and it must be in VBN 1.
	2) The LDBs must begin in VBN 2.
	3) All descriptors must be in the first LDB.
	4) Currently only works for real data, does not check to see if this is
		true or not.
	5) Midas file extensions (.bdf, .tbl) assumed lower case.

AUTHORS:
	FM   - F. Murtagh, ST-ECF
	SAV  - Stephen A. Voels, USM/DAN

MODIFICATION HISTORY:
	OCT 1988 FM   Initial programing and decoding of MIDAS files.
	FEB 1989 SAV  Name and calling sequence change.
		General reprograming for effeciency and modularity.
		Additional parameter checking.
	MAY 1989 FM   Minor change for case of 1-d images. 
	FEB 1991 FM   Conversion to V. 2 IDL, Unix.

(See /usr/local/idl/lib/zastron/disk_io/mid_rd_image.pro)

 NAME:
	MID_RD_TABLE

 PURPOSE:
	Open and read data from a MIDAS table.

 CALLING SEQUENCE:
	MID_RD_TABLE,table,ncol,nrow,data

 INPUTS:
	Table =  file name of MIDAS table or Logical Unit Number.  
	* If a filename is given, the file will be opened and closed
		using a local LUN. An extension -- not to be
		supplied -- of .TBL is assumed.  No version number is
		allowed: the most recent version is used.  
	* If an LUN is given, the file associated with that LUN will
		be used.

 OUTPUTS:
	Ncol =   number of columns in the input MIDAS table.  Long
		integer (I*4).
	Nrow =   number of rows in the MIDAS table. Long integer (I*4).
	Data =   table data.  Floating (R*4).  Data is of dimensions
		nrow*ncol.  The select column in the MIDAS table is 
		disregarded.

 ALGORITHM:
	We first consider the File Control Block of the MIDAS table file
	to determine the start of descriptor information and the start of
	the data. 
	Next we consider the Descriptor Directory Entry for `tblcontr' (the 
	number of columns and rows allocated; followed by the number of 
	columns and rows in the actual table).
	Finally we read the data values.

 RESTRICTIONS: 
	Real data handled only.  Midas table SELECTION mechanism is ignored.
	Also ignored are missing values.  
	Midas file extensions (.tbl) assumed lower case.

 AUTHORS:
	FM  -  Fionn Murtagh, ST-ECF, Munich.
	
 MODIFICATION HISTORY:
	OCT 1988  FM  Initial programming.
	MAY 1989  FM  Name change, debugging, etc.
	FEB 1991  FM  Conversion to V.2 IDL, Unix.

(See /usr/local/idl/lib/zastron/disk_io/mid_rd_table.pro)

 NAME:
	MID_UP_IMAGE

 PURPOSE:
	Get a pixel matrix and some support information from a MIDAS file.
	Allow updating of data, using DATA.

 CALLING SEQUENCE:
	MID_UP_IMAGE,IMAGE,DATA,NAXIS,NPIX

 INPUTS:
	IMAGE = Filename or Logical Unit Number.
	* If a filename is given, the file will be opened and closed using a
		local LUN.  The filename is that of the MIDAS image, without
		extension (.BDF will is assumed) or version number (latest 
		version is assumed).
	* If a LUN is given, the file associated with that LUN will be used.

 OUTPUTS:
	NAXIS = Number of dimensions in MIDAS image. I*4 values.
	NPIX  = Array containing the dimensions of the data to be written into
		the MIDAS image. Must be compatible with (i.e. smaller than or
		equal to the corresponding dimensions of) the latter. 
		I*4 values.
	DATA  = Array to be written into the MIDAS image. Dimensions are 
		defined by NAXIS and NPIX. R*4 values.

 ALGORITHM:
	0) Check inputs and set error handling.
	1) Open file for access using the access method indicated by the type of
		the input parameter IMAGE.
	2) Get the descriptors of the IMAGE.
		a) NAXIS set the output parameter NAXIS to this value.
		b) NPIX  set the output parameter NPIX to this value.
	3) Locate the pixel data start block
	4) Load pixel data into output parameter DATA
	5) Check consistency of dimensions of data array to be written, and
		image dimensions; then write data array into image.
	6) Terminate file access as is proper for the type of parameter IMAGE.

 RESTRICTIONS:
	1) There must be only one FCB and it must be in VBN 1.
	2) The LDBs must begin in VBN 2.
	3) All descriptors must be in the first LDB.
	4) Currently only works for real data, does not check to see if this is
		true or not.
	5) Midas extensions (.bdf, .tbl) assumed lower case.

 AUTHORS:
	FM   - F. Murtagh, ST-ECF
	SAV  - Stephen A. Voels, USM/DAN

 MODIFICATION HISTORY:
	MAY 1989  FM   Initial programming.
	FEB 1991  FM   Conversion to v.2 IDL, Unix.

(See /usr/local/idl/lib/zastron/disk_io/mid_up_image.pro)

 NAME:
	MID_UP_TABLE

 PURPOSE:
	Open and update data from a MIDAS table.

 CALLING SEQUENCE:
	MID_UP_TABLE,table,ncol,nrow,data

 INPUTS:
	Table =  file name of MIDAS table or Logical Unit Number.  
		* If a filename is given, the file will be opened and closed 
		using a local LUN.  An extension -- not to be
		supplied -- of .TBL is assumed.  No version number is
		allowed: the most recent version is used.  
		* If an LUN is given, the file associated with that LUN will be 
		used.
	Ncol =   number of columns in the array to be written into the 
		MIDAS table.  Long integer (I*4).  Must be less than or
		equal to the number of columns in the MIDAS table.
		"Ncol" and "nrow" are checked for consistency only.
	Nrow =   number of rows in the array to be written into the MIDAS 
		table. Long integer (I*4).  Must be less than or equal to
		the number of rows in the MIDAS table.
		"Ncol" and "nrow" are checked for consistency only.
	Data =   array of data to be written into the MIDAS table.  Floating 
		(R*4).  Data is of dimensions nrow*ncol.  The select column 
		in the MIDAS table is disregarded.

 RESTRICTIONS:
	Dimensions of the array to be written into the MIDAS table must be
	less than or equal to the corresponding dimensions of the latter.
	Note that in the case of smaller dimensions, only part of the given
	MIDAS table in altered (i.e. the 'upper left hand corner').
	No changes in the MIDAS table descriptors are carried out.  No 
	changes in the MIDAS table 'select' are carried out.
	Real data handled only.

	Midas extensions (.tbl) in lower case.

 OUTPUTS:
	None.

 ALGORITHM:
	We first consider the File Control Block of the MIDAS table file
	to determine the start of descriptor information and the start of
	the data. 
	Next we consider the Descriptor Directory Entry for `tblcontr' (the 
	number of columns and rows allocated; followed by the number of 
	columns and rows in the actual table).
	We check consistency between input array dimensions and the dimensions
	of the MIDAS table into which the array is to be written.
	Finally we carry out the writing of the data values.

 EXAMPLE:
	Given two MIDAS tables, PSF.TBL and PSF2.TBL, of the same dimensions;
	we wish to overwrite PSF2 with the contents of PSF.

	MID_RD_TABLE,'PSF',NC,NR,DAT
	DATTR = TRANSPOSE(DAT)
	MID_UP_TABLE,'PSF2',NC,NR,DATTR

 AUTHORS:
	FM - Fionn Murtagh, ST-ECF, Munich.

MODIFICATION HISTORY:
	OCT 1988  FM  Initial programming and decoding of MIDAS files.
	MAY 1989  FM  Name of routine changed; allowance made for LUN instead
		of table name; bug fixes.
	FEB 1991  FM  Conversion to V. 2, IDL, Unix.

(See /usr/local/idl/lib/zastron/disk_io/mid_up_table.pro)

 NAME:  
	READ_DST
 PURPOSE:  
	To read a DTA image file (default extension = .DST) of the format 
	used by DAOPHOT (CalTech data structure) from disk into an IDL array.

 CALLING SEQUENCE:  
	IMAGE = READ_DST(FILENAME)

 INPUT PARAMETER:  
	FILENAME - The name of a DTA image file residing on disk.  FILENAME
		should be pre-checked for validity.

 OUTPUT PARAMETER:
	IMAGE - 2-dimensional image array

 EXAMPLES:  
	PIC = READ_DST("M51_B.DST")

	Reads the DTA file "M51_B.DST" off the disk and loads the
	image into the variable PIC.  A default extension of .DST is
	assumed

 COMMON BLOCKS:  DTA
	DTA - The DTA common block contains all the header info, and
		may be accessed by another procedure.
 SUBROUTINES CALLED:
	DST_INFO
 SIDE EFFECTS:  
	Damn slow!
 NOTES:  
	This function was written in classic "hit-and-miss" fashion.  We
	were not positively clear on the true general format of DAOPHOT image 
	files so we played with a few files, trying to decipher the headers,
	and kept re-writing it until it worked on our files.  There is a 
	distinct possibility  that your image files contain something that 
	ours don't, and so, has not been taken into account.  If you find 
	such a case and success- fully fix it, please  let me know 
	(HYADES::PARKER).  Unfortunately the author did not comment the code, 
	and the variables are not too clear.

	Not tested on Unix machines

  PROCEDURE:  
	The DAOPHOT file is opened and the header information is read in one 
	record at a time.  The record is deciphered by the DST_INFO procedure.
	The header data are stored in the DTA common block, and the final image
	array is returned by the function.

 REVISION HISTORY:  
	03 AUG 87 written by Michael E. Van Steenberg
	17 OCT 89 toyed with by Joel Parker (cleaned and added
					comments & prolog)
	W. Landsman   August 1991    Unix compatibility 

(See /usr/local/idl/lib/zastron/disk_io/read_dst.pro)