| dafah |
|
Table of contents
Procedure
DAFAH ( DAF, assign handles )
SUBROUTINE DAFAH ( FNAME,
. FTYPE,
. ND,
. NI,
. IFNAME,
. RESV,
. HANDLE,
. UNIT,
. FHSET,
. ACCESS )
Abstract
Assign handles to DAFs as they are opened.
Required_Reading
DAF
Keywords
DAF
FILES
Declarations
IMPLICIT NONE
INCLUDE 'zzddhman.inc'
INTEGER INTEOC
PARAMETER ( INTEOC = 4 )
INTEGER LBCELL
PARAMETER ( LBCELL = -5 )
CHARACTER*(*) FNAME
CHARACTER*(*) FTYPE
INTEGER ND
INTEGER NI
CHARACTER*(*) IFNAME
INTEGER RESV
INTEGER HANDLE
INTEGER UNIT
INTEGER FHSET ( LBCELL : * )
CHARACTER*(*) ACCESS
Brief_I/O
VARIABLE I/O ENTRY POINTS
-------- --- --------------------------------------------------
FNAME I-O OPR, OPW, ONW, OPN (Obsolete), HFN, FNH
FTYPE I ONW
ND I-O ONW, OPN (Obsolete), HSF
NI I-O ONW, OPN (Obsolete), HSF
IFNAME I ONW, OPN (Obsolete)
RESV I ONW, OPN (Obsolete)
HANDLE I-O OPR, OPW, ONW, OPN (Obsolete), CLS, HLU, LUH, HFN,
FNH, SIH
UNIT I-O HLU, LUH
FHSET O HOF
ACCESS I SIH
RECL P OPR, OPW, ONW, OPN (Obsolete)
FTSIZE P OPR, OPW, ONW, OPN (Obsolete), CLS, HLU, LUH, HFN,
FNH
FILEN P SIH
Detailed_Input
FNAME on input, is the name of a DAF to be opened, or
the name of a DAF about which some information
(handle, logical unit) is requested.
FTYPE on input, is a code for the type of data that is
contained in the DAF file. This code has no meaning or
interpretation at the level of the DAF file
architecture, but is provided as a convenience for
higher level software. The maximum length for the file
type is four (4) characters. If the input string is
longer than four characters, the first nonblank
character and its three, or fewer, immediate nonblank
successors will be used as the file type. The file
type may not contain nonprinting characters, and it IS
case sensitive.
NAIF has reserved for its own use file types
consisting of the upper case letters (A-Z) and the
digits 0-9. NAIF recommends lower case or mixed case
file types be used by all others in order to avoid
any conflicts with NAIF file types.
ND on input, is the number of double precision components
in each array summary of a new file.
NI on input, is the number of integer components in each
array summary in a new file.
IFNAME is the internal file name for a DAF to be created.
RESV is the number of records to be reserved in a DAF
to be created.
HANDLE on input, is the handle of a DAF about which some
information (file name, logical unit) is requested,
or the handle of a DAF to be closed.
UNIT on input, is the logical unit connected to a DAF
about which some information (file name, handle) is
requested.
ACCESS is the type of access a DAF is open for, that is,
either reading or writing. The values of ACCESS
may be
'READ'
'WRITE'
Leading and trailing blanks are ignored, and case
is not significant.
Detailed_Output
FNAME on output, is the name of a DAF for which
the corresponding handle or logical unit has been
supplied.
ND on output, is the number of double precision
components in each array summary of an existing file.
NI on output, is the number of integer components in
each array summary in an existing file.
HANDLE on output, is the handle of a DAF for which
the corresponding file name or logical unit has been
supplied.
UNIT on output, is the logical unit connected to a DAF
for which the corresponding file name or handle has
been supplied.
FHSET is a SPICE set containing the handles of the
currently open DAFs.
Parameters
RECL is the record length of a DAF. Each record
must be large enough to hold 128 double
precision numbers or 1000 characters, whichever
is greater. The units in which the record length
must be specified vary from environment to
environment. For example, VAX Fortran requires
record lengths to be specified in longwords,
where two longwords equal one double precision
number. See the include file 'zzddhman.inc' for
details.
FTSIZE is the size of the file table maintained internally
by DAFAH. In effect, FTSIZE is the maximum number
of DAFs that the DAF routines allow to be open
simultaneously. See the include file 'zzddhman.inc'
for details.
FILEN is the maximum filename length. See the include file
'zzddhman.inc' for details.
INTEOC is the ASCII decimal integer code of the character
recognized by SPICE as representing the end of the
comment data in the reserved record area.
Exceptions
1) If DAFAH is called directly, the error SPICE(BOGUSENTRY)
is signaled.
2) See entry points DAFOPR, DAFOPW, DAFONW, DAFOPN, DAFCLS,
DAFHSF, DAFHLU, DAFLUH, DAFHFN, DAFNFH, DAFHOF, and DAFSIH for
exceptions specific to those entry points.
Files
All DAFs opened by this routine are specified by name.
Particulars
DAFAH serves as an umbrella, allowing data to be shared by its
entry points:
DAFOPR Open for read.
DAFOPW Open for write.
DAFONW Open new.
DAFOPN Open new. (Obsolete, use DAFONW )
DAFCLS Close.
DAFHSF Handle to summary format.
DAFHLU Handle to logical unit.
DAFLUH Logical to handle.
DAFHFN Handle to name.
DAFFNH File name to handle.
DAFHOF Handles of open files.
DAFSIH Signal invalid handles.
Before a DAF can be used, it must be opened. Entry points
DAFOPR and DAFOPW provide the only means for opening an
existing DAF.
Several files may be opened for use simultaneously. (This makes
it convenient to combine data from several files to produce a
single result.) As each DAF is opened, it is assigned a file
handle, which is used to keep track of the file internally, and
which is used by the calling program to refer to the file in all
subsequent calls to DAF routines.
DAFs may be opened for two kinds of access: read, and write.
Files opened for read access may not be changed in any way. Files
opened for write access may be both read and written.
DAFONW is used to open a new DAF file. This routine extends the
functionality of DAFOPN by providing a mechanism for associating a
type with the data in the DAF file. The use of this entry over
DAFOPN is highly recommended.
Since the only reason for creating a new file is to write
something in it, all new files are opened for write access.
Entry point DAFOPN, for opening a new DAF file, has been rendered
obsolete by the new entry point DAFONW. The entry point DAFOPN
will continue to be supported for purposes of backward
compatibility, but its use in new software development is
discouraged.
Entry point DAFCLS provides the only official means of closing
a DAF that is currently open. Closing a DAF any other way (for
example, by determining its logical unit and using the Fortran
CLOSE statement directly) may affect your calling program in
mysterious ways.
Entry point DAFHSF allows you to determine the summary format
of any DAF that is currently open, without calling DAFRFR to
re-read the file record.
Entry point DAFHOF allows you to determine which DAFs are open
at any time. In particular, you can use DAFHOF to determine
whether any file handle points to an open DAF.
Entry point DAFSIH signals errors when it is supplied with invalid
handles, so it serves to centralize error handling associated
with invalid handles.
The remaining entry points exist mainly to translate between
alternative representations of DAFs. There are three ways to
identify any open DAF: by name, by handle, and by logical
unit. Given any one of these, you may use these entry points to
find the other two.
Examples
See entry points DAFOPR, DAFOPW, DAFONW, DAFOPN, DAFCLS, DAFHSF,
DAFHLU, DAFLUH, DAFHFN, DAFNFH, DAFHOF, and DAFSIH for examples
specific to those entry points.
Restrictions
1) The value of parameter RECL may need to be changed when DAFAH
and its entry points are ported to a new environment (CPU and
compiler).
2) An integer overflow may occur if the number of files opened
by a single program exceeds the maximum number that can be
stored in an integer variable.
Literature_References
[1] "Sun FORTRAN Programmer's Guide", Sun Microsystems, Rev. A, 6
May 1988.
[2] "Microsoft Fortran Optimizing Compiler User's Guide",
Microsoft Corporation, 1987.
[3] "Lahey F77L EM/32 Programmers Reference Manual", version 4.0,
p 144.
[4] "Language Systems FORTRAN Reference Manual", Language Systems
Corporation, p 12-7.
[5] "FORTRAN/9000 Reference HP 9000 Series 700 Computers", 1st
Edition, June 1991, Hewlett Packard Company, page 5-110.
Author_and_Institution
N.J. Bachman (JPL)
J. Diaz del Rio (ODC Space)
K.R. Gehringer (JPL)
J.M. Lynch (JPL)
J.E. McLean (JPL)
H.A. Neilan (JPL)
M.J. Spencer (JPL)
W.L. Taber (JPL)
F.S. Turner (JPL)
I.M. Underwood (JPL)
E.D. Wright (JPL)
Version
SPICELIB Version 9.0.2, 25-NOV-2021 (JDR)
Edited the header of DAFAH umbrella routine and all its entry
points to comply with NAIF standard.
Added DAFOPR, DAFOPW, DAFCLS and DAFHSF header examples.
Corrected spelling mistakes.
SPICELIB Version 9.0.1, 10-OCT-2012 (EDW)
Edited DAFOPN $Abstract section to use "Deprecated" keyword
and state replacement routine.
Corrected ordering of all header sections.
Added a functional code example to the $Examples section
in DAFOPN and DAFCLS.
Removed the obsolete Reference citation to "NAIF
Document 167.0."
SPICELIB Version 9.0.0, 09-NOV-2006 (NJB)
Updated the entry point DAFONW so that a non-empty reserved
record area will also be a valid empty comment area. DAFONW
now writes a EOC character to the first byte of the second
record when the input number of reserved records NRESV is
greater than zero.
SPICELIB Version 8.1.0, 02-APR-2002 (FST)
Updated the following entry points in response to changes
to the handle manager interfaces:
DAFCLS
DAFOPR
DAFOPW
DAFONW
DAFOPN
See the $Revisions section for details.
Minor bug fix to DAFFNH. An error was signaled but the
intended call to CHKOUT and RETURN statement were omitted.
SPICELIB Version 8.0.0, 14-NOV-2000 (FST)
Cleaned up entry point headers by removing duplicate
entries from the $Revisions section where appropriate.
Integrated the new handle manager code into this module.
The number of DAFs the system can load is now 1000,
and some supported environments can read non-native
binary DAFs. See the Convert User's Guide for details.
SPICELIB Version 7.0.4, 08-OCT-1999 (WLT)
The environment lines were expanded so that the supported
environments are now explicitly given. New
environments are WIN-NT
SPICELIB Version 7.0.3, 16-SEP-1999 (NJB)
CSPICE environments were added. Some typos were corrected.
SPICELIB Version 7.0.2, 28-JUL-1999 (WLT)
The environment lines were expanded so that the supported
environments are now explicitly given. New
environments are PC-DIGITAL, SGI-O32 and SGI-N32.
SPICELIB Version 7.0.1, 22-MAR-1999 (WLT)
The environment lines were expanded so that the supported
environments are now explicitly given. Previously,
environments such as SUN-SUNOS and SUN-SOLARIS were implied
by the environment label SUN.
SPICELIB Version 7.0.0, 22-MAR-1999 (FST)
To accommodate the DAF FTP validation check, the following
entry points were modified:
DAFOPR, DAFOPW, DAFONW, DAFOPN.
See their headers and code for the details of the changes.
SPICELIB Version 6.0.0, 05-APR-1998 (NJB)
Added references to the PC-LINUX environment.
SPICELIB Version 5.1.0, 08-MAR-1996 (KRG)
The Following entry points have been modified: DAFONW and
DAFOPN.
The modifications support the notion of a DAF comment area,
and involve writing NULL filled reserved records when the
number of reserved records is greater than zero (0).
Some nested IF...THEN...ELSE IF...THEN...END IF constructs
were expanded to be independent IF...THEN...END IF tests.
The tests were for IOSTAT errors on cascading write statements
nested in the IF...ELSE IF... statements, and this was
confusing. These tests were restructured so that IOSTAT is
tested after each write statement which is equivalent to the
original intent and easier to read.
SPICELIB Version 5.0.0, 27-SEP-1993 (KRG)
The following entry points have had code modifications:
DAFOPR, DAFOPW and DAFOPN.
A new entry point has been added: DAFONW.
The modifications are to allow a type to be associated with a
DAF file.
A new parameter has been added to this subroutine's parameter
list, FTYPE, so that type information may be passed to the
entry point DAFONW. Two new variables were added to the
routine as well, TARCH and TTYPE, which provide temporary
storage for the file architecture and type.
Several new parameters have been added to the declarations for
this routine:
ARCLEN The length of a file architecture.
MAXPC The maximum decimal value for the range of
printable characters.
MINPC The minimum decimal value for the range of
printable characters.
TYPLEN The length of a file type.
See the individual entry points for detailed descriptions of
their modifications.
Removed the variables MINHAN and NIL, as they were not used in
any of the entry points, yet they had values assigned to them
through DATA statements.
Made all occurrences of error message formatting of filenames
consistent. All filenames will be single quoted in the output
error message.
SPICELIB Version 4.0.0, 25-FEB-1993 (JML)
In the entry points DAFOPR, DAFOPW, and DAFFNH, the INQUIRE
statement that checks if the file is already open now also
checks that the file exists.
IOSTAT is now checked after all INQUIRE statements.
A new variable LUN is used in DAFOPR, DAFOPW, and DAFOPN
for the logical unit number returned by GETLUN.
The IF-THEN statements in DAFOPR and DAFOPW were reorganized
to make the routines more readable.
In DAFOPR and DAFOPW, a long error message was added for the
case when the NAIF/DAF id word was not recognized. Also, the
file is closed when this error is signaled.
In DAFOPR and DAFOPW, IOSTAT is now checked after the file
record is read.
In DAFOPR, DAFOPW, DAFOPN, and DAFFNH, the file name is
checked to see if it is blank.
In DAFOPR, DAFOPW, DAFOPN, and DAFFNH, the file name passed
to the FORTRAN OPEN and INQUIRE statements has been chopped
at the last non-blank character.
A minor error in the $Particulars section of the header of
DAFCLS was corrected. It formerly stated that a file could be
open more than once for read or write access instead of just
read access.
SPICELIB Version 3.2.0, 06-OCT-1992 (HAN)
Module was updated to include the record length and source
for the Hewlett Packard UX 9000/750 environment. Moved FILEN
to the $Declarations section, and corrected $Revisions section
to include the last code change description, 3.1.0.
SPICELIB Version 3.1.1, 10-MAR-1992 (WLT)
Comment section for permuted index source lines was added
following the header.
SPICELIB Version 3.1.0, 13-NOV-1991 (MJS)
Module was updated to operate in the Lahey F77 EM/32
PC environment.
SPICELIB Version 3.0.0, 03-SEP-1991 (NJB) (WLT)
DAFAH and its entry points were modified to permit multiple
DAFs to be open for writing at the same time. Also, the
entry points DAFHOF and DAFSIH were added.
SPICELIB Version 2.0.0, 25-MAR-1991 (JEM) (MJS)
The variable MINHAN was initialized to zero and the variable
NEXT was saved. DAFOPW now accepts the ID word 'NAIF/NIP'
as well 'NAIF/DAF'. Spelling mistakes were corrected.
SPICELIB Version 1.1.0, 05-NOV-1990 (HAN)
The parameter FTSIZE was increased from 4 to 20.
SPICELIB Version 1.0.1, 22-MAR-1990 (HAN)
Literature references added to the header.
SPICELIB Version 1.0.0, 31-JAN-1990 (IMU)
|
Fri Dec 31 18:36:06 2021