CHAPTER 8 SAD DATA FORMAT MODULES
8.1 INTRODUCTION
These modules are all that is needed to use the SAD format
for application programs. A complete description of the lower
level routines called by these modules will be found in Chapter
11.
These subroutines are the preferred program interfaces to
the standard data format on disk. They are designed to be
independent of data structure and so provide a degree of immunity
from any possible future changes in data formats.
Notes:
1. USRINP is used by these routines wherever input is taken from
the terminal.
2. Errors are handled by the handler in the standard command
decoding package.
3. Just as a Fortran file is identified by a logical unit
number, so is a standard format file. The number must lie in the
range 11 to 20. Currently this corresponds directly to a Fortran
logical unit number and so logical units in the range 11 to 20
should not be used elsewhere in the same program.
4. The default file name is XX.SAD, where XX is the last used
SAD file.
5. The term "map" is synonymous to the term "image" in the
standard format specification.
8.2 DATA FORMAT
This package assumes the data is on disk in the standard SAD
data format with a number of maps arranged under a single node
(as written by current tape reading programs or created by
various MIIPS routines.).
In some contexts it is appropriate to operate on a single
map while elsewhere it is appropriate to access a set of maps.
For example: large two dimensional images are usually accessed
singly; sets of spectra or aperture synthesis maps are often
treated as a set. The routines provided here handle either case.
However, programmers should note that programming for sets of
maps is the preferred mode.
After access to a particular map has been established (with
CALL OPENMS), succeeding maps in the file may be considered as a
set of maps starting at the specified map, provided all maps have
the same array size. Map numbers within a set count from one
which corresponds to the map specified in the call to OPENMS. To
avoid confusion of map numbers, it is advisable that, where sets
of maps are being processed, each set start at the first map in
the file.
Page 2
8.3 OPENING AND CLOSING MAPS
8.3.1 OPENMS Routine
OPENMS opens a map as described in the previous section.
Details of the map may be contained in the call or requested from
the user. Information will be requested from the user
automatically if it is not present in the call. Alternate entry
points OPENCXMS and OPENDPMS are provided for opening complex and
double precision files respectively.
Calls:
CALL OPENMS(LU,MUSTEXIST,KEYWORD,FILENAME,ISTMAP,
1NMAPS,NPLNS,NROWS,NPIXELS)
CALL OPENCXMS(LU,MUSTEXIST,KEYWORD,FILENAME,ISTMAP,
1NMAPS,NPLNS,NROWS,NPIXELS)
CALL OPENDPMS (LU,MUSTEXIST,KEYWORD,FILENAME,ISTMAP,
1NMAPS,NPLNS,NROWS,NPIXELS)
where:
NAME I/O TYPE DESCRIPTION
NAME I/O TYPE DESCRIPTION
LU C I4 is the logical unit number to be associated
with the map. (See note 3 in
introduction.)
MUSTEXIST C LOG determines whether the map must exist prior
to being opened (i.e. whether it is being
opened for reading/updating or writing).
If is .FALSE. and map exists, gives no
error (message is: writing to an existing
file.) If is .TRUE. and map doesn't exist,
gives error.
KEYWORD C CHAR is the keyword to be used if file name is
requested from the user (see USRINP
documentation).
FILENAME C CHAR is the name of file containing the map. If
FILENAME is blank, the name is requested
from the user.
ISTMAP C I4 is the number of the map to be accessed.
Normally only values of 0 and 1 are used.
If ISTMAP is 1 , the file is treated
as a set of maps starting at the first map
in the file which is counted as number 1.
This option allows iterative operations on
a series of maps. All handling of map
number is done by the application module
rather than the I/O routines. For ISTMAP=N
and MUSTEXIST=.FALSE. the file is extended
Page 3
to map N.
If ISTMAP is 0, the number is
requested from the user; this option is
used when the calling module is written
specifically for a single map and the user
wants OPENMS to handle all aspects of
identifying the individual map. Note that
if this option is used, the map keyword in
user interaction is "MAP=".
Whenever an individual map is
requested in OPENMS, the MAPNO argument in
calls to other routines should be set to 1.
Do not make 2 succession calls to OPENMS
with MUSTEXIST=.FALSE. for the same file
because the map number will be read
incorrectly. You must use CLOSMS in
between. Be sure to call CLOSMS when done
with all other operations.
DOES MAP
MUSTEXIST ISTMAP ACTUALLY EXIST RESULT UPON OPENING
.TRUE. 0 YES User prompted for map
number (Error if map
number doesn't exist)
.TRUE. 1 YES OK
.TRUE. 0 NO ERROR
.TRUE. 1 NO ERROR
.FALSE. 0 YES Message: Writing to
an existing file
Prompt: Enter map
number (default=1
after last map) (can
create many at once)
.FALSE. N>=1 YES Message: Writing to
an existing file (If
N>number of maps)
creating new map
(could create many
at once)
.FALSE. 0 NO OK, creating new file,
asks for number of
pixels and rows
.FALSE. 1 NO OK, creating new file,
asks for number of
pixels and rows
NMAPS C/R I4 is the initial number of maps in file.
NPLNS C/R I4 is the number of planes in a map.
Currently equal to one.
NROWS C/R I4 is the number of rows in a map.
NPIXELS C/R I4 is the number of pixels in a row.
Page 4
Variables NMAPS, NPLNS, NROWS, NPIXELS must all be included or
all omitted. They are meaningful only when a new file is being
created. If they are not specified when a new file is created,
the map size is obtained from the user.
Examples:
CALL OPENMS(11,.TRUE.,'FILE=',' ',0)
File name and map number are obtained from the user and the map
is opened for reading/updating.
CALL OPENMS(11,.FALSE.,'FILE=','ABC',1,3,1,100,100)
File ABC.SAD is opened for writing and is to be treated as a set
of maps starting at the first map in the file. If the file
doesn't already exist, it is created with an initial size of
three maps each containing one plane of 100 rows by 100 pixels.
As noted above, only two dimensional maps are supported at this
stage so that NPLNS must always be one.
8.3.2 CLOSMS Routine
CLOSMS disassociates a map from a logical unit number.
Nothing gets written to the file if you don't call this.
Call:
CALL CLOSMS(LU)
where:
NAME I/O TYPE DESCRIPTION
NAME I/O TYPE DESCRIPTION
LU C I4 is the logical unit number associated with
map. (See note 3 in introduction.)
Page 5
8.4 MANIPULATING DATA HEADERS
This package supports the old BARST header read and write
routines, however, these are format dependent and should not be
used in future developments. The routines described below are
the preferred routines.
8.4.1 CHMHV/I4MHV/R4MHV/R8MHV Routines
These routines are called as functions returning CHARACTER,
4 4 8
INTEGER4, REAL4 and REAL8 map header values respectively. The
value desired is determined by a keyword given in the call.
Keywords should conform with FITS conventions.
Calls:
STRING = CHMHV(LU,MAPNO,KEYWORD,DEFAULT)
INTEGER = I4MHV(LU,MAPNO,KEYWORD,DEFAULT)
REAL4 = R4MHV(LU,MAPNO,KEYWORD,DEFAULT)
REAL8 = R8MHV(LU,MAPNO,KEYWORD,DEFAULT)
where:
NAME I/O TYPE DESCRIPTION
NAME I/O TYPE DESCRIPTION
LU C I4 is the logical unit number associated with
the map. (See note 3 in introduction.)
MAPNO C I4 is the number of the map within the set of
maps. (See discussion of ISTMAP in
description of OPENMS.)
KEYWORD C CHAR is the keyword corresponding to value
required. (Can have blanks) It is
different than USRINP keyword.
DEFAULT C is the default function value - used if
keyword is not defined in the header.
Variable type is the same as the function
type.
8.4.2 WRMHV/WRMHST Routines
WRMHV writes a map header numeric value to the specified
map. WRMHST writes a character string.
Calls:
CALL WRMHV(LU,MAPNO,KEYWORD,VALUE,FORMAT,COMMENT,DUPLICATE)
CALL WRMHST(LU,MAPNO,KEYWORD,STRING,FORMAT,COMMENT,DUPLICATE)
where:
NAME I/O TYPE DESCRIPTION
NAME I/O TYPE DESCRIPTION
LU C I4 is the logical unit number associated with
Page 6
the map. (See note 3 in introduction.)
MAPNO C I4 is the number of the map within the set of
maps. (See discussion of ISTMAP in
description of OPENMS.)
KEYWORD C CHAR is the keyword corresponding to the value
to be written.
VALUE C is the value to be written. Variable type
is determined by FORMAT.
STRING C CHAR is the character string to be written.
FORMAT C CHAR 'E', 'F', 'D' or 'I' correspond to Fortran
formats for numeric values. They are
ignored for WRMHST.
COMMENT C CHAR is the comment to be appended to the header
entry.
DUPLICATE C LOG determines whether to duplicate (.TRUE.) or
replace (.FALSE.) an existing value in
header.
8.4.3 READHD/WRITHD/READMHD/WRITMHD/READIHD/WRITIHD Routines
Calls:
CALL READHD(LU,HED,NI,NR)
CALL WRITHD(LU,HED,NI,NR)
where:
NAME I/O TYPE DESCRIPTION
NAME I/O TYPE DESCRIPTION
LU C I4 is the logical unit number
HED C/R R4 is the array of dimension NI:
Current usage of this array:
Index # Definition FITS Keyword
1,2,3 Not used
4 Heliocentric velocity CRVAL3
5 R.A. of reference location in degrees CRVAL1
6 Dec. of reference location in degrees CRVAL2
7 R.A. of reference location in gridunits CRPIX1
8 Dec. of reference location in gridunits CRPIX2
9 Left most gridpoint CSPIX1
10 Right most gridpoint
ll Bottom most gridpoint CSPIX2
12 Top most gridpoint
13 Not used
14 Scale in X in degrees/gridpoint CDELT1
15 Scale in Y in degrees/gridpoint CDELT2
Page 7
(C=Coordinate, S=Start, R=Reference)
NAME I/O TYPE DESCRIPTION
NAME I/O TYPE DESCRIPTION
NI C I4 is the dimension of HED. currently 15
NR C I4 is the record number. Use 0; formerly NR=
(
(MAPN-1) (NROWS + 1) from old BARST
rountines; is ignored now.
One can change values with HEDCH.FOR using OPTION MH in MIIPS.
CALL READMHD (LU,HED,NI,NR)
CALL WRITMHD (LU,HED,NI,NR)
These subroutines perform the same functions as READHD and
WRITHD, but they are used for 3-dimensional files.
CALL READIHD(LU,MAPN,HED,NI)
CALL WRITIHD(LU,MAPN,HED.NI)
These subroutines read and write the individual headers for each
map in a 3-dimensional file.
NAME I/O TYPE DESCRIPTION
NAME I/O TYPE DESCRIPTION
LU C I4 is the logical unit number
MAPN C i4 is the mapnumber
HED,NI C I4 is the dimension of the HED. currently 15
8.4.4 COPMHD Routine
COPMHD copies a map header from one map to another. Note
that only descriptive parameters such as units of measurement are
copied. Control parameters such as array sizes are not.
Call:
CALL COPMHD(LUIN,MAPNOIN,LUOUT,MAPNOOUT)
where:
NAME I/O TYPE DESCRIPTION
NAME I/O TYPE DESCRIPTION
LUIN,LUOUT C I4 are the logical unit numbers
associated with input and
output maps, respectively.
(See note 3 in
introduction.)
MAPNOIN, MAPNOOUT C I4 are the map numbers
associated with input and
output maps, respectively.
(See discussion of ISTMAP
in description of OPENMS.)
Page 8
8.4.5 MHKWCRD Routine
This character function reads keyword entries in a header
when the keywords are unknown. It is useful for operations such
as dumping the contents of a header. This is in the file
READHB.FOR. It is called by OPTION PH.
Call:
STRING = MHKWCRD(LU,MAPNO,NKEY,DEFAULT)
where:
NAME I/O TYPE DESCRIPTION
NAME I/O TYPE DESCRIPTION
STRING R CHAR is the 80 character keyword entry.
MAPNO C I4 is the number of the map within the set of
maps. (See discussion of ISTMAP in
description of OPENMS.)
NKEY C I4 is the number of the keyword to be read.
By incrementing this vaule until the
default is taken you can access all entries
in the keyword subdivision of the header.
DEFAULT C CHAR is the default keyword entry. The default
is used if NKEY is greater than the number
of keywords in the keyword subdivision.
8.4.6 NO_OF_MAPS Routine
NO_OF_MAPS returns the number of maps in a specified file.
Call:
NMAPS = NO_OF_MAPS(LU)
where:
NAME I/O TYPE DESCRIPTION
NAME I/O TYPE DESCRIPTION
NMAPS R I4 is the number of maps in the file
LU C I4 is the logical unit number associated with
the file. (See note 3 in introduction.)
Page 9
8.5 READING AND WRITING DATA
There are two varieties of data handling routines: those
that read whole rows and those that read sections of planes. It
is anticipated that higher dimensional routines will be available
in due course.
8.5.1 (RD/WR)MROW, (RD/WR)CXMROW, (RD/WR)DPMROW Routines
These routines read and write whole rows of real, complex
and double precision data respectively. RDMROW and WRMROW will
convert between any type data on disk and real data within the
program. The complex and double precision routines will give an
error if the disk data type does not match the program data type
(complex or double precision).
Calls:
CALL RDMROW(LU,MAPNO,DATA,LENGTH,NROW)
CALL WRMROW(LU,MAPNO,DATA,LENGTH,NROW)
CALL RDCXMROW(LU,MAPNO,DATA,LENGTH,NROW)
CALL WRCXMROW(LU,MAPNO,DATA,LENGTH,NROW)
CALL RDDPMROW(LU,MAPNO,DATA,LENGTH,NROW)
CALL WRDPMROW(LU,MAPNO,DATA,LENGTH,NROW)
where:
NAME I/O TYPE DESCRIPTION
NAME I/O TYPE DESCRIPTION
LU C I4 is the logical unit number associated with
the map. (See note 3 in introduction.)
MAPNO C I4 is the number the of map within the set.
(See discussion of ISTMAP in description of
OPENMS.)
DATA C/R is the data array. Data type must be
appropriate for particular subroutine.
LENGTH C I4 is the length of DATA array. It must be
sufficient to hold the whole row or else an
error will occur.
NROW C I4 is the number of the row to be read or
written (counting from one).
Page 10
8.5.2 (RD/WR)MXY, (RD/WR)CXMXY, (RD/WR)DPMXY Routines
These routines read and write plane sections of real,
complex and double precision data respectively. The data type
conversion constraints described in section 4.1 apply here also.
Calls:
CALL RDMXY(LU,MAPNO,DATA,LX,LY,ISX,ILX,ISY,ILY)
CALL WRMXY(LU,MAPNO,DATA,LX,LY,ISX,ILX,ISY,ILY)
CALL RDCXMXY(LU,MAPNO,DATA,LX,LY,ISX,ILX,ISY,ILY)
CALL WRCXMXY(LU,MAPNO,DATA,LX,LY,ISX,ILX,ISY,ILY)
CALL RDDPMXY(LU,MAPNO,DATA,LX,LY,ISX,ILX,ISY,ILY)
CALL WRDPMXY(LU,MAPNO,DATA,LX,LY,ISX,ILX,ISY,ILY)
where:
NAME I/O TYPE DESCRIPTION
LU C I4 is the logical unit associated with the
map. (See note 3 in introduction.)
MAPNO C I4 is the number of the map within the set of
maps. (See discussion of ISTMAP in
description of OPENMS.)
DATA C/R is the data array. The data type must be
appropriate to the particular subroutine.
LX,LY C I4 are the dimensions of array DATA.
ISX,ISY C I4 are the first column and row in the section
to be read or written. ISX and ISY are
given relative to the origin in the map
image (1,1) and always corresponds to the
origin of the array DATA. The actual
column and row must be offset by the start
coordinates IHED(9) and IHED(11) contained
in the header.
ILX,ILY C I4 are the number of columns and rows in
section to be written or read.
Page 11
8.6 SADFITS KEYWORDS
The following supplementary keywords have been defined for
use in FITS/SAD format files.
KEYWORD TYPE DESCRIPTION
$NAXIS1, I4 Used in cases when only a subset of the
$NAXIS2, field defined by NAXIS1, NAXIS2, NAXIS3 has
$NAXIS3 meaning. These keywords allow the same
image on disk to be reused several times
with different sized data. This is often
helpful when temporary files are being
used.
NINTEGR I4 Number of Integrations
DWELL I4 Integration Time (Seconds)
RA R4 Right Ascension (Degrees)
DEC R4 Declination (Degrees)
N.B. RA and DEC Keywords are used to
describe position independently of the
coordinate system defined by CRPIXn,
CRVALn, CDELTn, CTYPEn, CROTAn. They are
used when a position is known but for some
reason the coordinate system cannot be
expressed in RA or DEC.
HA R4 Hour Angle (Degrees)
ST R4 Sidereal Time (Degrees)
RUN I4 Run number
IPCS-MD CHAR IPCS mode ('1D', '2D', or 'XM')
IPCS-CD I4 Pseudo-central flag (1=True, 0=False).