| dafopw |
|
Table of contents
Procedure
DAFOPW ( DAF, open for write )
ENTRY DAFOPW ( FNAME, HANDLE )
Abstract
Open a DAF for subsequent write requests.
Required_Reading
DAF
Keywords
DAF
FILES
Declarations
CHARACTER*(*) FNAME
INTEGER HANDLE
Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
FNAME I Name of DAF to be opened.
HANDLE O Handle assigned to DAF.
Detailed_Input
FNAME is the name of a DAF to be opened with write access.
Detailed_Output
HANDLE is the file handle associated with the file. This handle
is used to identify the file in subsequent calls to other
DAF routines.
Parameters
None.
Exceptions
1) If the specified file has already been opened, either by the
DAF routines or by other code, an error is signaled by a
routine in the call tree of this routine. Note that this
response is not paralleled by DAFOPR, which allows you to open
a DAF for reading even if it is already open for reading.
2) If the specified file cannot be opened without exceeding the
maximum number of files, the error SPICE(DAFFTFULL) is
signaled.
3) If the attempt to read the file's file record fails, the error
SPICE(FILEREADFAILED) is signaled.
4) If the specified file is not a DAF file, an error is signaled
by a routine in the call tree of this routine.
5) If no logical units are available, an error is signaled by a
routine in the call tree of this routine.
6) If the file does not exist, an error is signaled by a routine
in the call tree of this routine.
7) If an I/O error occurs in the process of opening the file, the
error is signaled by a routine in the call tree of this
routine.
8) If the file name is blank or otherwise inappropriate, an error
is signaled by a routine in the call tree of this routine.
9) If the file was transferred improperly via FTP, an error is
signaled by a routine in the call tree of this routine.
10) If the file utilizes a non-native binary file format, an error
is signaled by a routine in the call tree of this routine.
Files
See argument FNAME.
Particulars
Most DAFs require only read access. If you do not need to
change the contents of a file, you should open it with DAFOPR.
Use DAFOPW when you need to
-- change (update) one or more summaries, names, or
arrays within a file; or
-- add new arrays to a file.
Examples
The numerical results shown for this example may differ across
platforms. The results depend on the SPICE kernels used as
input, the compiler and supporting libraries, and the machine
specific arithmetic implementation.
1) Delete the entire comment area of a DAF file. Note that this
action should only be performed if fresh new comments are to
be placed within the DAF file.
Use the SPK kernel below as input DAF file for the program.
earthstns_itrf93_201023.bsp
Example code begins here.
PROGRAM DAFOPW_EX1
IMPLICIT NONE
C
C SPICELIB functions
C
INTEGER RTRIM
C
C Local parameters
C
CHARACTER*(*) KERNEL
PARAMETER ( KERNEL =
. 'earthstns_itrf93_201023.bsp' )
INTEGER BUFFSZ
PARAMETER ( BUFFSZ = 10 )
INTEGER LINLEN
PARAMETER ( LINLEN = 1000 )
C
C Local variables.
C
CHARACTER*(LINLEN) BUFFER ( BUFFSZ )
INTEGER HANDLE
INTEGER I
INTEGER N
LOGICAL DONE
C
C Open a DAF for write. Return a HANDLE referring to the
C file.
C
CALL DAFOPW ( KERNEL, HANDLE )
C
C Print the first 10 lines of comments from the DAF file.
C
WRITE(*,'(A)') 'Comment area of input DAF file '
. // '(max. 10 lines): '
WRITE(*,'(A)') '---------------------------------------'
. // '-----------------------'
CALL DAFEC ( HANDLE, BUFFSZ, N, BUFFER, DONE )
DO I = 1, N
WRITE (*,*) BUFFER(I)(:RTRIM(BUFFER(I)))
END DO
WRITE(*,'(A)') '---------------------------------------'
. // '-----------------------'
WRITE(*,*) ' '
WRITE(*,*) 'Deleting entire comment area...'
C
C Delete all the comments from the DAF file.
C
CALL DAFDC ( HANDLE )
C
C Close the DAF file and re-open it for read
C access to work around the DAFEC restriction
C on comments not to be modified while they are
C being extracted.
C
CALL DAFCLS( HANDLE )
CALL DAFOPR( KERNEL, HANDLE )
C
C Check if the comments have indeed been deleted.
C
CALL DAFEC ( HANDLE, BUFFSZ, N, BUFFER, DONE )
IF ( DONE .AND. N .EQ. 0 ) THEN
WRITE(*,*) ' '
WRITE(*,*) ' Successful operation.'
ELSE
WRITE(*,*) ' '
WRITE(*,*) ' Operation failed.'
END IF
C
C Safely close the DAF.
C
CALL DAFCLS ( HANDLE )
END
When this program was executed on a Mac/Intel/gfortran/64-bit
platform, the output was:
Comment area of input DAF file (max. 10 lines):
--------------------------------------------------------------
SPK for DSN Station Locations
========================================================***
Original file name: earthstns_itrf93_2***
Creation date: 2020 October 28 12:30
Created by: Nat Bachman (NAIF***
Introduction
--------------------------------------------------------------
Deleting entire comment area...
Successful operation.
Warning: incomplete output. 3 lines extended past the right
margin of the header and have been truncated. These lines are
marked by "***" at the end of each line.
Restrictions
1) Only files of the native binary file format may be opened
with this routine.
2) Files opened using this routine must be closed with DAFCLS.
Literature_References
None.
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)
W.L. Taber (JPL)
F.S. Turner (JPL)
I.M. Underwood (JPL)
E.D. Wright (JPL)
Version
SPICELIB Version 8.1.2, 25-NOV-2021 (JDR)
Edited the header to comply with NAIF standard. Added complete
code example. Updated $Index_Entries.
SPICELIB Version 8.1.1, 10-OCT-2012 (EDW)
Corrected ordering of header section.
Removed the obsolete Reference citation to "NAIF
Document 167.0."
SPICELIB Version 8.1.0, 02-APR-2002 (FST)
This routine was updated to accommodate changes to the
handle manager interface. See DAFAH's Revision section
for details.
SPICELIB Version 8.0.0, 13-NOV-2001 (FST)
This routine was updated to utilize the new handle manager
software to manage binary file formats and consolidated
I/O code.
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, 17-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 6.0.0, 03-MAR-1999 (FST)
This entry point now attempts to locate and validate the
FTP validation string contained in the file record.
SPICELIB Version 5.0.0, 27-SEP-1993 (KRG)
This routine was modified to use a subroutine to obtain the
architecture of the file rather than using hard coded values
for comparing to the file ID word. This was done in order to
isolate the code which checks to determine a file architecture,
and to make the identification of file types easier through a
change to the file ID word.
In particular, the changes to this routine support the change
of the file ID word from 'NAIF/DAF' or 'NAIF/NIP' to 'DAF/xxxx'
where 'xxxx' represents a four character mnemonic code for the
type of data in the file.
Removed the error SPICE(DAFNOIDWORD) as it was no longer
relevant.
Added the error SPICE(NOTADAFFILE) if this routine is called
with a file that does not contain an ID word identifying the
file as a DAF file.
Changed the long error message when the error
SPICE(NOTADAFFILE) is signaled to suggest that a common error
is attempting to load a text version of the desired file rather
than the binary version.
SPICELIB Version 4.0.0, 25-FEB-1993 (JML)
The INQUIRE statement that checks if the file is already open
now also checks that the file exists.
A new variable LUN is used for the logical unit number
returned by GETLUN.
The IF-THEN statements were reorganized to improve readability.
A long error message is now set when the DAF id word is not
recognized. Also, the file is closed when this error is
signaled.
IOSTAT is now checked after the file record is read.
The file name is checked to see if it is blank.
The file name string that is passed to the FORTRAN OPEN and
INQUIRE statements has been chopped at the last non-blank
character.
SPICELIB Version 3.0.1, 10-MAR-1992 (WLT)
Comment section for permuted index source lines was added
following the header.
SPICELIB Version 3.0.0, 03-SEP-1991 (NJB) (WLT)
DAFOPW now allows multiple files to be open for writing.
This routine was updated so that it now keeps current the set
of DAF handles returned by DAFHOF.
SPICELIB Version 2.0.0, 24-JAN-1991 (JEM)
DAFOPW now accepts the ID word 'NAIF/NIP' as well 'NAIF/DAF'.
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:08 2021