STScI Logo

catquery xtools


NAME · SYNOPSIS · DESCRIPTION · NOTES · EXAMPLES

NAME

catquery -- catalog access package

SYNOPSIS

           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)

DESCRIPTION

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.

NOTES

The catquery package definitions file is cq.h.

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, cq_finfo, and cq_finfon routines. 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, cq_kinfo, and cq_kinfon routines. 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.

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)

    ...

Search Form · STSDAS