| dafec |
|
Table of contents
Procedure
DAFEC ( DAF extract comments )
SUBROUTINE DAFEC ( HANDLE, BUFSIZ, N, BUFFER, DONE )
Abstract
Extract comments from the comment area of a binary DAF.
Required_Reading
DAF
Keywords
FILES
UTILITY
Declarations
IMPLICIT NONE
INTEGER HANDLE
INTEGER BUFSIZ
INTEGER N
CHARACTER*(*) BUFFER(*)
LOGICAL DONE
Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
HANDLE I Handle of binary DAF opened with read access.
BUFSIZ I Maximum size, in lines, of BUFFER.
N O Number of extracted comment lines.
BUFFER O Buffer where extracted comment lines are placed.
DONE O Indicates whether all comments have been extracted.
Detailed_Input
HANDLE is the file handle of a binary DAF which has been opened
with read access.
BUFSIZ is the maximum number of comments that may be placed into
BUFFER. This would typically be the declared array size
for the Fortran character string array passed into this
routine.
Detailed_Output
N is the number of comment lines extracted from the comment
area of the binary DAF attached to HANDLE. This number
will be <= BUFSIZ on output. If N = BUFSIZ and DONE <>
.TRUE., then there are more comments left to to extract.
If N = 0, then DONE = .TRUE., i.e., there were no
comments in the comment area or we have extracted all
of the comments. If there are comments in the comment
area, or comments remaining after the extraction process
has begun, N > 0, always.
BUFFER is an array of at most BUFSIZ comments which have been
extracted from the comment area of the binary DAF
attached to HANDLE.
DONE is a logical flag indicating whether or not all of the
comment lines from the comment area of the DAF have
been read. This variable has the value .TRUE. after the
last comment line has been read. It will have the value
.FALSE. otherwise.
If there are no comments in the comment area, this
variable will have the value .TRUE., and N = 0.
Parameters
None.
Exceptions
1) If the size of the output line buffer is is not positive,
the error SPICE(INVALIDARGUMENT) is signaled.
2) If a comment line in a DAF is longer than the length
of a character string array element of BUFFER, the error
SPICE(COMMENTTOOLONG) is signaled.
3) If the end of the comments cannot be found, i.e., the end of
comments marker is missing on the last comment record, the
error SPICE(BADCOMMENTAREA) is signaled.
4) If the number of comment characters scanned exceeds the
number of comment characters computed, the error
SPICE(BADCOMMENTAREA) is signaled.
5) If the binary DAF attached to HANDLE is not open for reading,
an error is signaled by a routine in the call tree of this
routine.
Files
See argument HANDLE in $Detailed_Input.
Particulars
A binary DAF contains an area which is reserved for storing
annotations or descriptive textual information describing the data
contained in a file. This area is referred to as the ``comment
area'' of the file. The comment area of a DAF is a line
oriented medium for storing textual information. The comment
area preserves any leading or embedded white space in the line(s)
of text which are stored, so that the appearance of the of
information will be unchanged when it is retrieved (extracted) at
some other time. Trailing blanks, however, are NOT preserved,
due to the way that character strings are represented in
standard Fortran 77.
This routine will read the comments from the comment area of
a binary DAF, placing them into a line buffer. If the line
buffer is not large enough to hold the entire comment area,
the portion read will be returned to the caller, and the DONE
flag will be set to .FALSE. This allows the comment area to be
read in ``chunks,'' a buffer at a time. After all of the comment
lines have been read, the DONE flag will be set to .TRUE.
This routine can be used to ``simultaneously'' extract comments
from the comment areas of multiple binary DAFs. See Example
2 in the $Examples section.
Examples
The numerical results shown for these examples 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) The following example will extract a maximum of 30 lines
from the comment area of a binary DAF, displaying the
comments on the terminal screen.
Although it would be possible to read the 30 lines in one
go, for this example, use only a buffer size of 10,
demonstrating the use of the DONE logical flag.
Use the SPK kernel below as input DAF file for the program.
earthstns_itrf93_201023.bsp
Example code begins here.
PROGRAM DAFEC_EX1
IMPLICIT NONE
C
C SPICELIB functions
C
INTEGER RTRIM
C
C Local parameters
C
CHARACTER*(*) KERNEL
PARAMETER ( KERNEL =
. 'earthstns_itrf93_201023.bsp' )
INTEGER BUFSIZ
PARAMETER ( BUFSIZ = 10 )
INTEGER LINLEN
PARAMETER ( LINLEN = 1000 )
C
C Local variables.
C
CHARACTER*(LINLEN) BUFFER ( BUFSIZ )
INTEGER HANDLE
INTEGER I
INTEGER J
INTEGER N
LOGICAL DONE
C
C Open a DAF for read. Return a HANDLE referring to the
C file.
C
CALL DAFOPR ( KERNEL, HANDLE )
C
C Read a maximum of 30 lines of comments.
C
WRITE(*,'(A)') 'Comment area of input DAF file '
. // '(max. 30 lines): '
WRITE(*,'(A)') '---------------------------------------'
. // '-----------------------'
DO I = 0, 2
CALL DAFEC ( HANDLE, BUFSIZ, N, BUFFER, DONE )
C
C Write the N lines to the terminal screen.
C
DO J = 1, N
WRITE (*,*) BUFFER(J)(:RTRIM(BUFFER(J)))
END DO
END DO
WRITE(*,'(A)') '---------------------------------------'
. // '-----------------------'
C
C Have all the comments been read?
C
IF ( .NOT. DONE ) THEN
WRITE(*,*) ' '
WRITE(*,*) 'Warning: Not all comments have been read!'
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. 30 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
========================================================***
This file provides geocentric states---locations and vel***
set of DSN stations cited in the list below under "Posit***
position vectors point from the earth's barycenter to th***
velocities are estimates of the derivatives with respect***
vectors; in this file, velocities are constant. Station ***
magnitudes on the order of a few cm/year.
The states in this file are given relative to the terres***
frame ITRF93.
This SPK file has a companion file
earthstns_fx_201023.bsp
which differs from this one only in that it uses the ref***
frame alias 'EARTH_FIXED'. See the comment area of that ***
and the Frames Required Reading for details.
--------------------------------------------------------------
Warning: Not all comments have been read!
Warning: incomplete output. 12 lines extended past the right
margin of the header and have been truncated. These lines are
marked by "***" at the end of each line.
2) The following example demonstrates the use of this routine to
simultaneously read the comment areas of multiple DAFs. For
each file, the comments will be displayed on the screen as
they are extracted.
Use the SPK kernel below as the first DAF file for the
program.
earthstns_itrf93_201023.bsp
Use the CK kernel below as the second DAF file for the
program.
vo2_swu_ck2.bc
Example code begins here.
PROGRAM DAFEC_EX2
IMPLICIT NONE
C
C SPICELIB functions
C
INTEGER RTRIM
LOGICAL ALLTRU
C
C Local parameters
C
INTEGER BUFSIZ
PARAMETER ( BUFSIZ = 10 )
INTEGER FNAMLN
PARAMETER ( FNAMLN = 255 )
INTEGER LINLEN
PARAMETER ( LINLEN = 1000 )
INTEGER NUMFIL
PARAMETER ( NUMFIL = 2 )
C
C Local variables.
C
CHARACTER*(FNAMLN) DAFNAM ( NUMFIL )
CHARACTER*(LINLEN) BUFFER ( BUFSIZ )
INTEGER HANDLE ( NUMFIL )
INTEGER I
INTEGER J
INTEGER N
LOGICAL DONE ( NUMFIL )
C
C Set the DAF file names.
C
DATA DAFNAM /
. 'earthstns_itrf93_201023.bsp',
. 'vo2_swu_ck2.bc' /
C
C Set the initial values for DONE and HANDLE.
C
DO I = 1, NUMFIL
DONE(I) = .FALSE.
HANDLE(I) = 0
END DO
C
C Open the DAFs.
C
DO I = 1, NUMFIL
CALL DAFOPR ( DAFNAM(I), HANDLE(I) )
END DO
C
C While there are still some comments left to read in at
C least one of the files, read them and display them.
C
DO WHILE ( .NOT. ALLTRU( DONE, NUMFIL ) )
DO I = 1, NUMFIL
IF ( .NOT. DONE(I) ) THEN
WRITE (*,*)
WRITE (*,*) 'File: ',
. DAFNAM(I)(:RTRIM(DAFNAM(I)))
WRITE (*,*) '---------------------------------'
. // '-----------------------------'
N = 0
CALL DAFEC ( HANDLE(I), BUFSIZ, N,
. BUFFER, DONE(I) )
DO J = 1, N
WRITE (*,*) BUFFER(J)(:RTRIM(BUFFER(J)))
END DO
END IF
END DO
END DO
C
C Safely close the DAF files.
C
DO I = 1, NUMFIL
CALL DAFCLS ( HANDLE(I) )
END DO
END
When this program was executed on a Mac/Intel/gfortran/64-bit
platform, the output was:
File: earthstns_itrf93_201023.bsp
--------------------------------------------------------------
SPK for DSN Station Locations
========================================================***
Original file name: earthstns_itrf93_2***
Creation date: 2020 October 28 12:30
Created by: Nat Bachman (NAIF***
Introduction
File: vo2_swu_ck2.bc
--------------------------------------------------------------
\beginlabel
PDS_VERSION_ID = PDS3
RECORD_TYPE = FIXED_LENGTH
RECORD_BYTES = 1024
^SPICE_KERNEL = "vo2_swu_ck2.bc"
MISSION_NAME = VIKING
SPACECRAFT_NAME = "VIKING ORBITER 2"
DATA_SET_ID = "VO1/VO2-M-SPICE-6-V1.0"
KERNEL_TYPE_ID = CK
PRODUCT_ID = "vo2_swu_ck2.bc"
File: earthstns_itrf93_201023.bsp
--------------------------------------------------------------
========================================================***
This file provides geocentric states---locations and vel***
set of DSN stations cited in the list below under "Posit***
position vectors point from the earth's barycenter to th***
velocities are estimates of the derivatives with respect***
vectors; in this file, velocities are constant. Station ***
magnitudes on the order of a few cm/year.
The states in this file are given relative to the terres***
File: vo2_swu_ck2.bc
--------------------------------------------------------------
PRODUCT_CREATION_TIME = 2008-12-03T14:03:35
PRODUCER_ID = "NAIF/JPL"
MISSION_PHASE_NAME = {
PRIMARY_MISSION,
EXTENDED_MISSION,
CONTINUATION_MISSION
}
PRODUCT_VERSION_TYPE = ACTUAL
PLATFORM_OR_MOUNTING_NAME = "SPACECRAFT BUS"
START_TIME = 1977-01-09T18:33:12.707
File: earthstns_itrf93_201023.bsp
--------------------------------------------------------------
frame ITRF93.
This SPK file has a companion file
earthstns_fx_201023.bsp
which differs from this one only in that it uses the ref***
frame alias 'EARTH_FIXED'. See the comment area of that ***
and the Frames Required Reading for details.
File: vo2_swu_ck2.bc
--------------------------------------------------------------
STOP_TIME = 1977-11-27T05:55:16.772
SPACECRAFT_CLOCK_START_COUNT = "1/0032380393.707"
SPACECRAFT_CLOCK_STOP_COUNT = "1/0060155717.772"
TARGET_NAME = MARS
INSTRUMENT_NAME = "SCAN PLATFORM"
NAIF_INSTRUMENT_ID = -30000
SOURCE_PRODUCT_ID = "N/A"
NOTE = "See comments in the file fo***
OBJECT = SPICE_KERNEL
INTERCHANGE_FORMAT = BINARY
File: earthstns_itrf93_201023.bsp
--------------------------------------------------------------
Revision description
--------------------
This kernel contains data from a single, current source:***
This kernel supersedes the kernels
earthstns_itrf93_050714.bsp
dss_53_prelim_itrf93_201018.bsp (data in this kernel ***
File: vo2_swu_ck2.bc
--------------------------------------------------------------
KERNEL_TYPE = POINTING
DESCRIPTION = "VO2 instrument platform ori***
reconstructed during cartographic image registration by S. ***
Type 2 CK file supersedes the less usable Type 1 CK vo2_swu***
END_OBJECT = SPICE_KERNEL
\endlabel
[...]
Warning: incomplete output. Only 100 out of 1049 lines have
been provided. 18 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) The comment area may consist only of printing ASCII
characters, decimal values 32 - 126.
2) There is NO maximum length imposed on the significant portion
of a text line that may be placed into the comment area of a
DAF. The maximum length of a line stored in the comment area
should be kept reasonable, so that they may be easily
extracted. A good value for this would be 1000 characters, as
this can easily accommodate ``screen width'' lines as well as
long lines which may contain some other form of information.
3) This routine is only used to read records on environments
whose characters are a single byte in size. Updates
to this routine and routines in its call tree may be
required to properly handle other cases.
4) This routine is intended to be used on DAF files whose comment
area does not change while this routine is called to extract
comments, between the start and end of the extraction process.
If the comment area does change (gets updated, reduced,
extended, or deleted) between calls to this routine on the
same DAF file, the routine's outputs are undefined and
subsequent calls to it are likely to trigger an exception.
Literature_References
None.
Author_and_Institution
N.J. Bachman (JPL)
J. Diaz del Rio (ODC Space)
K.R. Gehringer (JPL)
B.V. Semenov (JPL)
F.S. Turner (JPL)
Version
SPICELIB Version 1.2.0, 25-NOV-2021 (JDR) (BVS)
Added IMPLICIT NONE statement.
Edited the header to comply with NAIF standard. Removed
unnecessary $Revisions section.
Added complete code examples from existing code fragments.
SPICELIB Version 1.1.0, 12-APR-2012 (BVS)
Increased FTSIZE (from 1000 to 5000).
SPICELIB Version 1.0.0, 08-NOV-2006 (NJB) (KRG) (FST)
Based on Support Version 2.0.0, 16-NOV-2001 (FST)
|
Fri Dec 31 18:36:07 2021