1 /* getlun.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 GETLUN ( Get a free logical unit ) */
getlun_(integer * unit)9 /* Subroutine */ int getlun_(integer *unit)
10 {
11 /* System generated locals */
12 integer i__1;
13
14 /* Local variables */
15 extern /* Subroutine */ int chkin_(char *, ftnlen), fndlun_(integer *),
16 sigerr_(char *, ftnlen), chkout_(char *, ftnlen), setmsg_(char *,
17 ftnlen), errint_(char *, integer *, ftnlen);
18 extern logical return_(void);
19
20 /* $ Abstract */
21
22 /* Return the number of a free logical unit. */
23
24 /* $ Disclaimer */
25
26 /* THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE */
27 /* CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S. */
28 /* GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE */
29 /* ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE */
30 /* PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS" */
31 /* TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY */
32 /* WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A */
33 /* PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC */
34 /* SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE */
35 /* SOFTWARE AND RELATED MATERIALS, HOWEVER USED. */
36
37 /* IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA */
38 /* BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT */
39 /* LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND, */
40 /* INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS, */
41 /* REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE */
42 /* REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY. */
43
44 /* RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF */
45 /* THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY */
46 /* CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE */
47 /* ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE. */
48
49 /* $ Required_Reading */
50
51 /* None. */
52
53 /* $ Keywords */
54
55 /* FILES */
56
57 /* $ Declarations */
58 /* $ Brief_I/O */
59
60 /* VARIABLE I/O DESCRIPTION */
61 /* -------- --- -------------------------------------------------- */
62 /* UNIT O The number of a free logical unit. */
63
64 /* $ Detailed_Input */
65
66 /* None. */
67
68 /* $ Detailed_Output */
69
70 /* UNIT is the number of a free logical unit (also called */
71 /* an "external unit"). If no free units are available, */
72 /* the value of UNIT is 0. */
73
74 /* $ Parameters */
75
76 /* None. */
77
78 /* $ Exceptions */
79
80 /* 1) If there are no free logical units available, UNIT is assigned */
81 /* the value 0, and the error SPICE(NOFREELOGICALUNIT) is */
82 /* signalled. */
83
84 /* 2) This routine obtains a logical unit number from FNDLUN. */
85 /* FNDLUN executes a Fortran INQUIRE statement; if that statement */
86 /* fails to execute properly, FNDLUN returns a negative unit */
87 /* number. In this case, GETLUN assigns the value 0 to UNIT, */
88 /* and the error SPICE(INQUIREFAILED) is signalled. */
89
90 /* $ Files */
91
92 /* None. */
93
94 /* $ Particulars */
95
96 /* GETLUN returns the number of the first (unreserved) unit not */
97 /* currently connected to a file. It thus frees the user from */
98 /* having to maintain an accounting of which units are open, which */
99 /* are closed, and which are available. */
100
101 /* This routine is related to the routines FNDLUN, RESLUN, and */
102 /* FRELUN. Together, these routines support coordinated usage of */
103 /* Fortran logical units. GETLUN (Get a free logical unit) and */
104 /* FNDLUN (Find a free logical unit) both have the function of */
105 /* returning a logical unit number that is not reserved or already */
106 /* in use. The principal difference between the functionality of */
107 /* these routines is that GETLUN both returns a status code and */
108 /* signals an error if a free unit is not found, while FNDLUN */
109 /* merely returns a status code. */
110
111 /* RESLUN is used to reserve logical unit numbers, so that they will */
112 /* not be returned by GETLUN or FNDLUN; FRELUN frees logical units */
113 /* previously reserved via calls to RESLUN. */
114
115 /* Logical units 5-7 are reserved by default. Other units may be */
116 /* reserved by calling RESLUN. Once reserved, units (except 5-7) may */
117 /* be unreserved by calling FRELUN. */
118
119 /* To reserve logical unit numbers for special use, refer to */
120 /* RESLUN. To make reserved units available to GETLUN or FNDLUN, */
121 /* refer to FRELUN. */
122
123 /* A unit returned by GETLUN does NOT automatically become a */
124 /* reserved unit. If the user wishes to reserve a unit found by */
125 /* GETLUN, the call to GETLUN must be followed by a call to RESLUN. */
126
127 /* This routine obtains a logical unit number via a call to FNDLUN. */
128 /* FNDLUN uses an INQUIRE statement; if that statement doesn't */
129 /* execute properly, GETLUN will signal the error. This arrangement */
130 /* allows FNDLUN to be error free. */
131
132 /* The range of possible unit numbers returned by GETLUN is dependent */
133 /* on the parameters MINLUN and MAXLUN, which are defined in FNDLUN. */
134
135 /* Note that although 0 is a valid logical unit number on some */
136 /* systems, a value of 0 returned by GETLUN indicates that no free */
137 /* logical unit was available, rather than that logical unit 0 is */
138 /* available. */
139
140 /* $ Examples */
141
142 /* The following code fragment illustrates the use of GETLUN. */
143
144 /* CALL GETLUN ( UNIT ) */
145
146 /* IF ( UNIT .EQ. 0 ) THEN */
147 /* RETURN */
148 /* END IF */
149
150 /* $ Restrictions */
151
152 /* This routine never returns a logical unit number of 0. The */
153 /* value 0 is used to indicate that no free logical unit was */
154 /* found. */
155
156 /* $ Literature_References */
157
158 /* None. */
159
160 /* $ Author_and_Institution */
161
162 /* N.J. Bachman (JPL) */
163 /* C.A. Curzon (JPL) */
164 /* H.A. Neilan (JPL) */
165 /* I.M. Underwood (JPL) */
166
167 /* $ Version */
168
169 /* - SPICELIB Version 1.0.2, 18-MAY-2010 (BVS) */
170
171 /* Removed "C$" marker from text in the header. */
172
173 /* - SPICELIB Version 1.0.1, 10-MAR-1992 (WLT) */
174
175 /* Comment section for permuted index source lines was added */
176 /* following the header. */
177
178 /* - SPICELIB Version 1.0.0, 31-JAN-1990 (CAC) (IMU) */
179
180 /* -& */
181 /* $ Index_Entries */
182
183 /* get a free logical unit */
184
185 /* -& */
186 /* $ Revisions */
187
188 /* - Beta Version 2.0.0, 24-FEB-1989 (HAN) (NJB) */
189
190 /* This routine has been substantially re-written so as to */
191 /* obtain a free logical unit number via a call to FNDLUN. */
192
193 /* If there are no free logical units available, UNIT */
194 /* is assigned the value 0, and an error is signalled. */
195
196 /* The "Parameters" section was added to the header. */
197
198 /* -& */
199
200 /* Spicelib functions */
201
202
203 /* Standard SPICE error handling. */
204
205 if (return_()) {
206 return 0;
207 } else {
208 chkin_("GETLUN", (ftnlen)6);
209 }
210
211 /* Find a free logical unit, if there's one to be had. */
212
213 fndlun_(unit);
214 if (*unit == 0) {
215
216 /* There are no free units to be had. C'est la vie. Signal an */
217 /* error. */
218
219 setmsg_("No free logical units are available.", (ftnlen)36);
220 sigerr_("SPICE(NOFREELOGICALUNIT)", (ftnlen)24);
221 chkout_("GETLUN", (ftnlen)6);
222 return 0;
223 } else if (*unit < 0) {
224
225 /* There are no free units to be had. In this case, we know the */
226 /* "INQUIRE" attempted by FNDLUN failed. Assign 0 to the unit */
227 /* number, and signal an error. */
228
229 setmsg_("INQUIRE iostat was #.", (ftnlen)21);
230 i__1 = -(*unit);
231 errint_("#", &i__1, (ftnlen)1);
232 sigerr_("SPICE(INQUIREFAILED)", (ftnlen)20);
233 *unit = 0;
234 chkout_("GETLUN", (ftnlen)6);
235 return 0;
236 }
237 chkout_("GETLUN", (ftnlen)6);
238 return 0;
239 } /* getlun_ */
240
241