1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
|
CATQUERY: The Catalog and Survey Access Routines
1. Introduction
The catquery package provides a set of routines for local and remote
catalog and image survey server access. The supported catalogs and image
surveys are described in records stored in a catalog and image survey
configuration file respectively. The catalog and image survey records
specify the network address, the query format, and the output format for
each supported catalog or image display server. More detailed information
about catalogs and image survey access and configuration files can be
found by typing "help catalogs" and "help surveys".
The results of each catalog query are stored in memory in an IRAF spool
file. Calling programs can access the catalog results sequentially or randomly
by record number. Individual fields in each record can be decoded into
floating point, integer, or string values.
The results of each image survey query are written to an image file on disk,
currently a fits image file. IRAF image i/o routines can be used to access
the image. There must be enough space availale on the disk to receive the
image.
2. The Interface Routines
The package prefix is cq. The interface routines are listed below.
cq = cq_map (file, mode)
ival = cq_stati (cq, param)
cq_stats (cq, param, str, maxch)
nlines = cq_statt (cq, param, text, maxch)
catno = cq_locate (cq, name)
catno = cq_locaten (cq, catno, catname, maxch)
catno = cq_setcat (cq, name)
catno = cq_setcatn (cq, catno)
[ird]val = cq_fget[ird] (cq, name)
nelems = cq_fga[ird] (cq, name, array[ird], max_nelems)
cq_fgstr (cq, name, str, maxch)
cq_fgwrd (cq, name, wrd, maxch)
nlines = cq_fgtext (cq, name, text, maxch)
stat = cq_scan (cq)
nqpars = cq_nqpars (cq)
qparno = cq_gqpar (cq, name, qpname, max_qpname, qpvalue,
max_qpvalue, qpunits, max_qpunits, qpformat,
max_qpformat)
qparno = cq_gqparn (cq, qparno, qpname, max_qpname, qpvalue,
max_qpvalue, qpunits, max_qpunits, qpformat, max_qpformat)
qparno = cq_sqpar (cq, name, valuestr)
qparno = cq_sqparn (cq, qparno, valuestr)
res = cq_query (cq)
res = cq_fquery (cq, catfile, cathdr)
ival = cq_rstati (res, param)
cq_rstats (res, param, str, maxch)
nlines = cq_rstatt (res, param, text, maxch)
hparno = cq_hinfo (res, name, hpvalue, max_hpvalue)
hparno = cq_hinfon (res, hparno, hpname, max_hpname, hpvalue,
max_hpvalue)
nchars = cq_grecord (res, buffer, maxch, recno)
nchars = cq_gnrecord (res, buffer, maxch, nextrec)
fieldno = cq_finfo (res, name, foffset, fsize, ftype, funits,
max_funits, formats, max_formats)
fieldno = cq_finfon (res, fieldno, fname, max_fname, foffset, fsize,
ftype, funits, max_funits, formats, max_formats)
cq_rclose (res)
nchars = cq_gval[silrd] (res, name, [silrd]val)
nchars = cq_gvalc (res, name, str, maxch)
imres = cq_imquery (cq, imname)
imres = cq_fimquery (cq, imname)
ival = cq_istati (imres, param)
cq_istats (imres, param, str, maxch)
nlines = cq_istatt (imres, param, text, maxch)
wparno = cq_winfo (imres, name, wkname, max_wkname, wvalue,
max_wvalue, wtype, wunits, max_wunits)
wparno = cq_winfon (imres, wparno, wpname, max_wpnane, wkname,
max_wkname, wvalue, max_wvalue, wtype, wunits, max_wunits)
kparno = cq_kinfo (imres, name, skname, max_skname, svalue,
max_svalue, stype, sunits, max_sunits)
kparno = cq_kinfon (imres, kparno, spname, max_spname, skname,
max_skname, svalue, max_svalue, stype, sunits, max_sunits)
cq_imclose (imres)
cq_unmap (cq)
3. Notes
An "include <pkg/cq.h>" statement must appear in the calling program to
make the catquery pacakge parameter definitions visible to the calling program.
A "-lxtools" must be included in the calling program link line to link in
the catquery routines.
The catalog and image surveys configuration files are mapped and unmapped
with the routines cq_map and cq_unmap.
Before making a query the calling program must set the current catalog
or image survey with the cq_setcat or cq_setcatn routines, and format
and set the query parameters with the cq_gqpar, cq_gqparn, and cq_sqparn
routines.
Remote and locate catalog queries are made with the cq_query routine.
The routines cq_rstat[ist] are used to retrieve the catalog results parameters.
Header parameter values and field descriptions can be retrieved with
the cq_hinfo / cq_hinfon and cq_finfo / cq_finfon routines respectively.
Catalog records can be accessed sequentially or randomly with the cq_gnrecord
and cq_grecord routines. The cq_gval[csilrd] routines can be used to decode
the record fields into floating point, integer, or string values. The
cq_fquery routine is used to make a catalog file emulate the results of a
catalog query. Cq_rclose frees the catalog results descriptor.
Remote and locate image survey queries are made with the cq_imquery routine.
The routines cq_istat[ist] are used to retrieve the survey results parameters.
The standard wcs and image parameter descriptions can be retrieved with the
the cq_winfo / cq_winfon and cq_kinfo / cq_kinfon routines respectively. The
cq_fimquery routine is used to make an existing image emulate the results of
an image survey query. Cq_imclose frees the survey results descriptor.
4. Examples
Example 1: Query a catalog and dump the results to a catalog file.
include <cq.h>
....
ra = clgetd ("ra")
dec = clgetd ("dec")
width = clgetd ("width")
....
# Open the catalog configuration file.
cq = cq_map ("astromz$lib/catdb.dat", READ_ONLY)
if (cq == NULL)
...
# Set the catalog.
catno = cq_setcat (cq, "noao@usno2")
if (catno == 0)
...
# Set the query parameters. Assume the input input units match the
# the expected units. The input size is a width so divide by two
# if the query expects a radius.
nqpars = cq_nqpars (cq)
do i = 1, nqpars {
parno = cq_gqparn (cq, i, qpname, CQ_SZ_QPNAME, qpvalue,
CQ_SZ_QPVALUE, qpunits, CQ_SZ_QPUNITS, qpformats
CQ_SZ_QPFORMATS)
if (parno != i)
next
if (streq (qpname, "ra")) {
call sprintf (qpvalue, CQ_SZ_QPVALUE, qpformats)
call pargd (ra)
parno = cq_sqpars (cq, qpname, qpvalue)
} else if (streq (qpname, "dec")) {
call sprintf (qpvalue, CQ_SZ_QPVALUE, qpformats)
call pargd (dec)
parno = cq_sqpars (cq, qpname, qpvalue)
} else if (streq (qpname, "radius")) {
call sprintf (qpvalue, CQ_SZ_QPVALUE, qpformats)
call pargd (width / 2.0d0)
parno = cq_sqpars (cq, qpname, qpvalue)
} else if (streq (qpname, "width")) {
call sprintf (qpvalue, CQ_SZ_QPVALUE, qpformats)
call pargd (width)
parno = cq_sqpars (cq, qpname, qpvalue)
} else if (streq (qpname, "xwidth")) {
call sprintf (qpvalue, CQ_SZ_QPVALUE, qpformats)
call pargd (width)
parno = cq_sqpars (cq, qpname, qpvalue)
} else if (streq (qpname, "ywidth")) {
call sprintf (qpvalue, CQ_SZ_QPVALUE, qpformats)
call pargd (width)
parno = cq_sqpars (cq, qpname, qpvalue)
}
}
# Make the query.
res = cq_query (cq)
if (res == NULL)
...
# Write the results to a file.
recptr = 0
while (cq_gnrecord (res, buffer, SZ_LINE, rectpr) != EOF) {
call fprintf (outfd, "%s")
call pargstr (buffer)
}
# Close the query.
call cq_rclose (res)
# Close the database.
call cq_unmap (cq)
Example 2: Repeat the previous example but only output records for
which magnitude values <= 16.0.
include <cq.h>
...
res = cq_query (cq)
if (res == NULL)
...
nrec = cq_rstati (res, CQNRECS)
do i = 1, nrecs {
nchars = cq_gvalr (res, i, "mag1", mag)
if (nchars <= 0)
next
if (mag > 16.0)
next
nchars = cq_grecord (res, buffer, SZ_LINE, i)
if (nchars <= 0)
next
call fprintf (outfd, "%s")
call pargstr (buffer)
}
call cq_rclose (res)
...
Example 3: Make an image survey query and dump the results to a fits file.
include <cq.h>
....
ra = clgetd ("ra")
dec = clgetd ("dec")
width = clgetd ("width")
....
# Open the catalog configuration file.
cq = cq_map ("astromz$lib/imdb.dat", READ_ONLY)
if (cq == NULL)
...
# Set the catalog.
catno = cq_setcat (cq, "dss1@cadc")
if (catno == 0)
...
# Set the query parameters. Assume the input input units match the
# the expected units.
nqpars = cq_nqpars (cq)
do i = 1, nqpars {
parno = cq_gqparn (cq, i, qpname, CQ_SZ_QPNAME, qpvalue, CQ_SZ_QPVALUE,
qpunits, CQ_SZ_QPUNITS, qpformats, CQ_SZ_QPFORMATS)
if (parno != i)
next
if (streq (qpname, "ra")) {
call sprintf (qpvalue, CQ_SZ_QPVALUE, qpformats)
call pargd (ra)
parno = cq_sqpars (cq, qpname, qpvalue)
} else if (streq (qpname, "dec")) {
call sprintf (qpvalue, CQ_SZ_QPVALUE, qpformats)
call pargd (dec)
parno = cq_sqpars (cq, qpname, qpvalue)
} else if (streq (qpname, "width")) {
call sprintf (qpvalue, CQ_SZ_QPVALUE, qpformats)
call pargd (width)
parno = cq_sqpars (cq, qpname, qpvalue)
} else if (streq (qpname, "xwidth")) {
call sprintf (qpvalue, CQ_SZ_QPVALUE, qpformats)
call pargd (width)
parno = cq_sqpars (cq, qpname, qpvalue)
} else if (streq (qpname, "ywidth")) {
call sprintf (qpvalue, CQ_SZ_QPVALUE, qpformats)
call pargd (width)
parno = cq_sqpars (cq, qpname, qpvalue)
}
}
# Make the query.
imres = cq_imquery (cq, "outimage.fits")
if (imres == NULL)
...
# Free the results structure
call cq_imclose (imres)
# Unmap the database
call cq_unmap (cq)
Example 4: Repeat the previous example but convert the dss wcs to a fits wcs.
At_mkdss is a routine which converts a dss wcs to a fits wcs
...
# Make the query.
imres = cq_imquery (cq, "outimage.fits")
if (imres == NULL)
...
wcstype = cq_istati (imres, CQWCS)
if (wcstype == CQWDSS) {
im = immap ("outimage.fits", READ_WRITE, 0)
stat = at_mkdss (im, true, false)
if (stat == ERR)
...
call imunmap (im)
}
# Free the results structure
call cq_imclose (imres)
...
|
