1 /* dskopn.f -- translated by f2c (version 19980913).
2 You must link the resulting object file with the libraries:
3 -lf2c -lm (in that order)
4 */
5
6 #include "f2c.h"
7
8 /* $Procedure DSKOPN ( DSK, open new file ) */
dskopn_(char * fname,char * ifname,integer * ncomch,integer * handle,ftnlen fname_len,ftnlen ifname_len)9 /* Subroutine */ int dskopn_(char *fname, char *ifname, integer *ncomch,
10 integer *handle, ftnlen fname_len, ftnlen ifname_len)
11 {
12 extern /* Subroutine */ int chkin_(char *, ftnlen), dlaopn_(char *, char *
13 , char *, integer *, integer *, ftnlen, ftnlen, ftnlen), chkout_(
14 char *, ftnlen);
15 extern logical return_(void);
16
17 /* $ Abstract */
18
19 /* Open a new DSK file for subsequent write operations. */
20
21 /* $ Disclaimer */
22
23 /* THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE */
24 /* CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S. */
25 /* GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE */
26 /* ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE */
27 /* PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS" */
28 /* TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY */
29 /* WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A */
30 /* PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC */
31 /* SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE */
32 /* SOFTWARE AND RELATED MATERIALS, HOWEVER USED. */
33
34 /* IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA */
35 /* BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT */
36 /* LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND, */
37 /* INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS, */
38 /* REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE */
39 /* REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY. */
40
41 /* RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF */
42 /* THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY */
43 /* CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE */
44 /* ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE. */
45
46 /* $ Required_Reading */
47
48 /* DAS */
49 /* DSK */
50
51 /* $ Keywords */
52
53 /* DAS */
54 /* DSK */
55 /* FILES */
56
57 /* $ Declarations */
58
59 /* Include file dla.inc */
60
61 /* This include file declares parameters for DLA format */
62 /* version zero. */
63
64 /* Version 3.0.1 17-OCT-2016 (NJB) */
65
66 /* Corrected comment: VERIDX is now described as a DAS */
67 /* integer address rather than a d.p. address. */
68
69 /* Version 3.0.0 20-JUN-2006 (NJB) */
70
71 /* Changed name of parameter DSCSIZ to DLADSZ. */
72
73 /* Version 2.0.0 09-FEB-2005 (NJB) */
74
75 /* Changed descriptor layout to make backward pointer */
76 /* first element. Updated DLA format version code to 1. */
77
78 /* Added parameters for format version and number of bytes per */
79 /* DAS comment record. */
80
81 /* Version 1.0.0 28-JAN-2004 (NJB) */
82
83
84 /* DAS integer address of DLA version code. */
85
86
87 /* Linked list parameters */
88
89 /* Logical arrays (aka "segments") in a DAS linked array (DLA) file */
90 /* are organized as a doubly linked list. Each logical array may */
91 /* actually consist of character, double precision, and integer */
92 /* components. A component of a given data type occupies a */
93 /* contiguous range of DAS addresses of that type. Any or all */
94 /* array components may be empty. */
95
96 /* The segment descriptors in a SPICE DLA (DAS linked array) file */
97 /* are connected by a doubly linked list. Each node of the list is */
98 /* represented by a pair of integers acting as forward and backward */
99 /* pointers. Each pointer pair occupies the first two integers of a */
100 /* segment descriptor in DAS integer address space. The DLA file */
101 /* contains pointers to the first integers of both the first and */
102 /* last segment descriptors. */
103
104 /* At the DLA level of a file format implementation, there is */
105 /* no knowledge of the data contents. Hence segment descriptors */
106 /* provide information only about file layout (in contrast with */
107 /* the DAF system). Metadata giving specifics of segment contents */
108 /* are stored within the segments themselves in DLA-based file */
109 /* formats. */
110
111
112 /* Parameter declarations follow. */
113
114 /* DAS integer addresses of first and last segment linked list */
115 /* pointer pairs. The contents of these pointers */
116 /* are the DAS addresses of the first integers belonging */
117 /* to the first and last link pairs, respectively. */
118
119 /* The acronyms "LLB" and "LLE" denote "linked list begin" */
120 /* and "linked list end" respectively. */
121
122
123 /* Null pointer parameter. */
124
125
126 /* Segment descriptor parameters */
127
128 /* Each segment descriptor occupies a contiguous */
129 /* range of DAS integer addresses. */
130
131 /* The segment descriptor layout is: */
132
133 /* +---------------+ */
134 /* | BACKWARD PTR | Linked list backward pointer */
135 /* +---------------+ */
136 /* | FORWARD PTR | Linked list forward pointer */
137 /* +---------------+ */
138 /* | BASE INT ADDR | Base DAS integer address */
139 /* +---------------+ */
140 /* | INT COMP SIZE | Size of integer segment component */
141 /* +---------------+ */
142 /* | BASE DP ADDR | Base DAS d.p. address */
143 /* +---------------+ */
144 /* | DP COMP SIZE | Size of d.p. segment component */
145 /* +---------------+ */
146 /* | BASE CHR ADDR | Base DAS character address */
147 /* +---------------+ */
148 /* | CHR COMP SIZE | Size of character segment component */
149 /* +---------------+ */
150
151 /* Parameters defining offsets for segment descriptor elements */
152 /* follow. */
153
154
155 /* Descriptor size: */
156
157
158 /* Other DLA parameters: */
159
160
161 /* DLA format version. (This number is expected to occur very */
162 /* rarely at integer address VERIDX in uninitialized DLA files.) */
163
164
165 /* Characters per DAS comment record. */
166
167
168 /* End of include file dla.inc */
169
170 /* $ Brief_I/O */
171
172 /* Variable I/O Description */
173 /* -------- --- -------------------------------------------------- */
174 /* FNAME I Name of a DSK file to be opened. */
175 /* IFNAME I Internal file name. */
176 /* NCOMCH I Number of comment characters to allocate. */
177 /* HANDLE O Handle assigned to the opened DSK file. */
178
179 /* $ Detailed_Input */
180
181 /* FNAME is the name of a new DSK file to be created. The */
182 /* file will be left opened for write access. */
183
184 /* IFNAME is the internal file name for the new file. The name */
185 /* may contain as many as 60 characters. All characters */
186 /* of IFNAME should be printing characters (ASCII codes */
187 /* 32-126 decimal). This name should uniquely identify */
188 /* the file. */
189
190 /* NCOMCH is the number of comment characters to allocate. */
191 /* Allocating comment characters at file creation time */
192 /* may reduce the likelihood of having to expand the */
193 /* comment area later. */
194
195 /* $ Detailed_Output */
196
197 /* HANDLE is the file handle associated with the file. This */
198 /* handle is used to identify the file in subsequent */
199 /* calls to other DSK routines. */
200
201 /* $ Parameters */
202
203 /* None. */
204
205 /* $ Exceptions */
206
207 /* 1) If the input filename is blank, the error will be diagnosed */
208 /* by routines in the call tree of this routine. No file will */
209 /* be created. */
210
211 /* 2) If the specified file cannot be opened without exceeding the */
212 /* maximum allowed number of open DAS files, the error will be */
213 /* diagnosed by routines in the call tree of this routine. No */
214 /* file will be created. */
215
216 /* 3) If the file cannot be opened properly, the error will be */
217 /* diagnosed by routines in the call tree of this routine. No */
218 /* file will be created. */
219
220 /* 4) If the initial records in the file cannot be written, the */
221 /* error is diagnosed by routines in the call tree of this */
222 /* routine. No file will be created. */
223
224 /* 5) If no logical units are available, the error will be */
225 /* diagnosed by routines in the call tree of this routine. No */
226 /* file will be created. */
227
228 /* 6) If the internal file name contains nonprinting characters */
229 /* (ASCII codes decimal 0-31 and 127-255), the error will be */
230 /* diagnosed by routines in the call tree of this routine. No */
231 /* file will be created. */
232
233 /* 7) If the number of comment characters allocated NCOMCH is */
234 /* negative, the error will be diagnosed by routines in the call */
235 /* tree of this routine. No file will be created. */
236
237 /* $ Files */
238
239 /* See argument FNAME. */
240
241 /* $ Particulars */
242
243 /* DSK files are built using the DLA low-level format and */
244 /* the DAS architecture; DLA files are a specialized type of DAS */
245 /* file in which data are organized as a doubly linked list of */
246 /* segments. Each segment's data belong to contiguous components of */
247 /* character, double precision, and integer type. */
248
249 /* This routine creates a new DSK file and sets the type of the */
250 /* file to the mnemonic code passed to it. */
251
252 /* DSK files created by this routine have initialized file records. */
253 /* The ID word in a DSK file record has the form */
254
255 /* DAS/DSK */
256
257 /* where the characters following the slash are supplied by the */
258 /* caller of this routine. */
259
260 /* $ Examples */
261
262 /* 1) Create a new DSK file, using an internal file name that */
263 /* attempts to serve as an unique identifier. No room for */
264 /* comments will be reserved. */
265
266 /* FNAME = 'TEST.DSK' */
267 /* IFNAME = 'TEST.DSK/NAIF/NJB/20-OCT-2006/14:37:00' */
268 /* NCOMCH = 0 */
269
270 /* CALL DSKOPN ( FNAME, IFNAME, NCOMCH, HANDLE ) */
271
272 /* $ Restrictions */
273
274 /* None. */
275
276 /* $ Literature_References */
277
278 /* None. */
279
280 /* $ Author_and_Institution */
281
282 /* N.J. Bachman (JPL) */
283
284 /* $ Version */
285
286 /* - SPICELIB Version 1.0.0, 08-FEB-2017 (NJB) */
287
288 /* Corrected a few header typos. */
289
290 /* 29-APR-2010 (NJB) */
291
292 /* Now passes NCOMCH to DLAOPN. */
293
294 /* 08-OCT-2009 (NJB) */
295
296 /* Updated header. */
297
298 /* 20-OCT-2006 (NJB) */
299
300 /* -& */
301 /* $ Index_Entries */
302
303 /* open a new dsk file */
304 /* open a new dsk file with write access */
305
306 /* -& */
307
308 /* SPICELIB functions */
309
310 if (return_()) {
311 return 0;
312 }
313 chkin_("DSKOPN", (ftnlen)6);
314 dlaopn_(fname, "DSK", ifname, ncomch, handle, fname_len, (ftnlen)3,
315 ifname_len);
316 chkout_("DSKOPN", (ftnlen)6);
317 return 0;
318 } /* dskopn_ */
319
320