# E.S.O. - VLT project/ESO Archive
# $Id: astro_catalog.man3,v 1.1.1.1 2009/03/31 14:11:52 cguirao Exp $
#
# This file is processed by the ESO/VLT docDoManPages command to
# produce a man page in nroff, TeX and MIF formats. 
# See docDoManPages(1) for a description of the input format.
# 
# who             when       what
# --------------  ---------  --------------------------------------
# Allan Brighton  16 Oct 95  Created
#

NAME
astroCatalog - C library for accessing astromical catalogs

SYNOPSIS
#include "astroCatalog.h"

typedef void* AcHandle; 

typedef void* AcResult;

AcHandle acOpen(char* name);

void acClose(AcHandle);

int acMore(AcHandle);

int acNumCols(AcHandle)

char* acColName(AcHandle, int col);

char** acColNames(AcHandle);

int acColIndex(AcHandle handle, char* name);

char* acGetError();
int acGetErrorCode();

int acGetDescription(
    AcHandle cat,
    int* numCols,
    char*** colNames);

int acGetObject(
    AcHandle cat,
    char* id,
    int numCols,
    char** colNames,
    AcResult* result);
    
int acGetArea(
    AcHandle cat,
    int numCols,
    char** colNames,
    double ra0,
    double dec0,		
    double ra1,		
    double dec1,
    double mag0,
    double mag1,
    int maxRows,
    char* filename,
    int* numFound,
    AcResult* result);

int acCircularSearch(
    AcHandle cat,
    int numCols,
    char** colNames,
    double ra,
    double dec,		
    double radius0,
    double radius1,
    double mag0,
    double mag1,
    int maxRows,
    char* filename,
    int* numFound,
    AcResult* result);

int acSearchClosestStar(
    AcHandle cat,
    int numCols,
    char** colNames,
    double ra,
    double dec,		
    double mag0,
    double mag1,
    AcResult* result);

int acCatalogSearch(
    AcHandle cat,
    int numCols,
    const char* const* colNames,
    int numSearchCols,
    char** searchCols,
    const char* const* minVals,
    const char* const* maxVals,
    int maxRows,
    const char* filename,
    int* numFound,
    AcResult* result);

/*
 *  --- routines for accessing the query results ---
 */

int acrNumRows(AcResult);

int acrNumCols(AcResult);

char** acrColNames(AcResult);
 
int acrGetString(AcResult, int row, int col, char** value);
int acrGetInt(AcResult, int row, int col, int* value);
int acrGetDouble(AcResult, int row, int col, double* value);
int acrGetFloat(AcResult, int row, int col, float* value);
int acrGetShort(AcResult,int row, int col, short* value);
int acrGetChar(AcResult,int row, int col, char* value);

int acrGetNString(AcResult,int row, const char* colName, char** value);
int acrGetNInt(AcResult,int row, const char* colName, int* value);
int acrGetNDouble(AcResult,int row, const char* colName, double* value);
int acrGetNFloat(AcResult,int row, const char* colName, float* value);
int acrGetNShort(AcResult,int row, const char* colName, short* value);
int acrGetNChar(AcResult,int row, const char* colName, char* value);

int acrGetWC(AcResult, int row, WC* pos);

int acrColIndex(AcResult,const char* colName);

void acrDelete(AcResult);


DESCRIPTION
This man page describes a library for accessing astronomical catalogs
from C applications in a generic way.

Note: Although the library is implemented in C++, it also defines a C
interface, which is described here.  To use this library from C, an
application must have a C++ main and be linked with the C++
compiler. This is easily done by renaming the C main to c_main and
defining a C++ main that calls it.

The main purpose of this library is to provide generic access to a
variety of astronomical catalogs available locally or on the network.
The interface hides the details of accessing the various catalogs and
shows their contents in a uniform way.

CATALOG SERVERS
This class communicates with a catalog server via HTTP requests. The
list of servers and how to access them is kept in a configuration
file, which is also accessed via HTTP. The default config file is:

    http://archive.eso.org/skycat/skycat.cfg

The default can be overridden by defining the environment variable
SKYCAT_CONFIG to another valid HTTP URL.

LOCAL CATALOGS
If the catalog name passed to acOpen is the name of a file, it is
taken to be a local catalog file in the format used by the Starbase
utilities. A local catalog is an ASCII file containing an optional
title and header information followed by the column headings, a dashed
line and the data rows. The columns are separated by tabs. This is
also the format of query results returned via HTTP from remote catalog
servers.

Example:

Table1
id	ra	dec	pos-e	mag
------	--	---	-----	---
A00050	3:19:28	8:26:29	0.2	13.49
A00098	3:19:32	8:34:15	0.4	13.40
A00288	3:19:21	8:31:19	0.2	13.13
A00314	3:19:44	8:30:58	0.2	13.98

The pointer returned from acOpen for files is a pointer to an object
for accessing local catalogs. The interface is the same for remote and
local catalogs, only the implementation is different.

QUERY PARAMETERS
Parameters for catalog searches are checked to make sure they are
valid and in the correct range. A radius value must be between 0.0 and
300.0 arcmin.  A magnitude may have any value. For ranges, such as min
and max radius and min and max magnitude, the order of the arguments
is not important, since they will be rearranged as needed. If both min
and max values are 0.0, they are ignored for that search. If you
really want to search for objects with "0.0" magnitude, specify a
range with small values that are not zero, for example, min/max mag =
(-0.0001, +0.0001).

FORMAT OF QUERY RESULTS
Query results are accessed by a set of routines that operate on a an
"AcResult" object that is returned as the last argument in the query
routine calls. The object keeps a table of result rows and columns
internally and provides an interface for extracting the values in
various formats and data types. The format of query results in a file
was described above (see LOCAL CATALOGS).

ROUTINE NAMES
Note that the astroCatalog routine names all have the prefix "ac",
while the routines that operate on the query results all have the
prefix "acr".

MEMORY MANAGEMENT
Memory is allocated for the query results. It is the caller's
responsibility to delete the result object with the acrDelete()
routine when it is no longer needed.

ERROR HANDLING
Most of the routines described here return non-zero on error and zero
if all is OK (routines that return pointers return a NULL pointer on
error). The text of the error message can be retrieved with the
acGetError() function and an error code is available via the
acGetErrorCode function. The error codes are the same as those in
<errno.h> and have the same meanings (EINVAL means invalid operand -
or parameter, 0 means no code was available). 

UNITS
Unless otherwise stated, the units for all radius values are in arcmin.
Floating point values for RA and DEC are always in degrees. The
default equinox is J2000.

ASTRO CATALOG C ROUTINES
acOpen
	Open the named catalog and return a handle for it. The handle
	can be used in subsequent operations on the catalog. If the
	catalog can not be opened, NULL is returned and an error
	message can be retrieved with acGetError().

	Arguments:
		name (in) - Catalog name, (long or short name) from the
			    catalog config file.
	Return value: 
		Catalog handle for use in future calls. Use acClose() to
		free resources when no longer needed.

acClose
	Close the given catalog and free its resources.

	Arguments:
		handle (in) - Catalog handle returned from acOpen().
	Return value: 
		None

acGetDescription
	Get the number of columns and the column names for the given
	catalog and return 0 if all is OK. The memory for the return
	arrays is managed internally and should not be modified by the
	caller.

	Arguments:
		handle   (in ) - Catalog handle returned from acOpen().
   		numCols  (out) - Number of catalog columns.
    		colNames (out) - Pointer to array of column names.
	Return value: 
		If successful, 0, otherwise 1.

   
acGetObject	
	Get the values for the specified columns for the object given
	by "id" in the catalog and return 0 if there are no
	errors. The id should be a valid object id obtained by a
	previous catalog query.  If colNames is not NULL, it should be
	an array of "numCols" column names to fetch, otherwise all
	columns are fetched.  "result" is set to point to an AcResult
	object for accessing the catalog values found (it may be
	empty). The memory for the result is allocated (see MEMORY
	MANAGEMENT above).

    	Arguments:
		handle    (in ) - Catalog handle.
   		id        (in ) - Object id.
    		numCols   (in ) - Number of column names specified 
    		colNames  (in ) - Array[numCols] of column names to 
				  read, or NULL to read all columns.
   		result (in/out) - Handle for accessing query results.
	Return value: 
		Returns 0 on success, 1 for errors. It is not considered
		an error if no object is found. Use acrNumRows(result)	
		to determine if an object was found.
	Comment:
		An error is returned if the catalog does not support
		query by Id. The GSC server now supports this, but 
		older versions of the catalog config file do not have
		the new URL for this yet.

acGetArea
	Get the values for all objects in the rectangular region given
	by the two world coordinate points. If mag0 and mag1 are not
	0.0, they are taken to be the minimum and maximum magnitude
	values for the query. If colNames is not NULL, it should be an
	array of numCols column names to fetch, otherwise all columns
	are fetched. The number of object rows returned is limited to
	maxRows (the acMore() routine can be called to see if more
	objects would have been available).
	On return, numFound is set to the number of objects found and,
	if any were found, "result" is set to point to an AcResult
	object for accessing the catalog values found. The memory for
	the result is allocated (see MEMORY MANAGEMENT above). 
	If filename is not NULL, the results will be copied to the
	given file in the format of a local catalog.

	Arguments:
		handle    (in ) - Catalog handle.
    		numCols   (in ) - Number of column names specified.
    		colNames  (in ) - Array[numCols] of column names to 
				  read, or NULL to read all.
		ra0       (in ) - World coordinates of first point
		dec0	  (in ) - in degrees.
		ra1	  (in ) - World coordinates of second point
		dec1	  (in ) - in degrees.
		mag0	  (in ) - Min magnitude.
		mag1	  (in ) - Max magnitude.
		maxRows   (in ) - Max number of rows to return.
		filename  (in ) - If not null, write results to this 
				  file.
		numFound  (out) - Set to number of objects found.
   		result (in/out) - Handle for accessing query results.
	Return value: 
		If successful, 0, otherwise 1.
	Comment:
		An error is returned is the catalog does not support
		area querries.
			
acCircularSearch		
	Get the values for all objects in the circle or ring given by
	the world coordinate point and the min and max radius values.
	If mag0 and mag1 are not 0.0, they are taken to be the minimum
	and maximum magnitude values for the query. If colNames is not
	NULL, it should be an array of column names to fetch,
	otherwise all columns are fetched. The number of object rows
	returned is limited to maxRows (the acMore() routine can be
	called to see if more objects would have been available).
	On return, numFound is set to the number of objects found and,
	if any were found, "result" is set to point to an AcResult
	object for accessing the catalog values found. The memory for
	the result is allocated (see MEMORY MANAGEMENT above).
	If filename is not NULL, the results will be copied to the
	given file in the format of a local catalog.

	Arguments:
		handle    (in ) - Catalog handle.
    		numCols   (in ) - Number of column names specified.
    		colNames  (in ) - Array[numCols] of column names to
				  read, or NULL to read all.
		ra        (in ) - World coordinates of center point
		dec	  (in ) - in degrees.
		radius0	  (in ) - Min radius from center point.
		radius1	  (in ) - Max radius from center point.
		mag0	  (in ) - Min magnitude.
		mag1	  (in ) - Max magnitude.
		maxRows   (in ) - Max number of rows to return.
		filename  (in ) - If not null, write results to this 
				  file.
		numFound  (out) - Number of objects found.
   		result (in/out) - Handle for accessing query results.
	Return value: 
		If successful, 0, otherwise 1.


acSearchClosestStar	
	Get the values for the specified columns for the object in the
	catalog closest to the given position and return 0 if there
	are no errors. If colNames is not NULL, it should be an array
	of column names to fetch, otherwise all columns are
	fetched. If mag0 and mag1 are not 0.0, they are taken to be
	the minimum and maximum magnitude values for the query.
	"result" is set to point to an AcResult object for accessing
	the catalog values found (it may be empty if none were
	found). The memory for the result is allocated (see MEMORY
	MANAGEMENT above).

    	Arguments:
		handle    (in ) - Catalog handle.
    		numCols   (in ) - Number of column names specified.
    		colNames  (in ) - Array[numCols] of column names to 
				  read, or NULL to read all columns.
		ra        (in ) - World coordinates of point
		dec	  (in ) - in degrees.
		mag0	  (in ) - Min magnitude.
		mag1	  (in ) - Max magnitude.
   		result (in/out) - Handle for accessing query results.
	Return value: 
		Returns 0 on success, 1 for errors. It is not considered
		an error if no object is found. Use acrNumRows(result)	
		to determine if an object was found.
			
acCatalogSearch	
	Get the values for all objects fulfilling the specified
	criteria.  The criteria are given by the array of column names
	to compare and two arrays of the same size containing min and
	max values, in string format, corresponding to the column
	names. Null strings are ignored, so, for example, if there is
	no min value, only the max value will be used.  If colNames is
	not NULL, it should be an array of column names to fetch,
	otherwise all columns are fetched. The number of object rows
	returned is limited to maxRows (the acMore() routine can be
	called to see if more objects would have been available).  On
	return, numFound is set to the number of objects found and, if
	any were found, "result" is set to point to an AcResult object
	for accessing the catalog values found. The memory for the
	result is allocated (see MEMORY MANAGEMENT above).
	If filename is not NULL, the results will be copied to the
	given file in the format of a local catalog.

	Arguments:
		handle    (in ) - Catalog handle.
    		numCols   (in ) - Number of column names specified. 
    		colNames  (in ) - Array[numCols]  of column  names to
                                  read, or NULL to read all.
		numSearchCols (in ) - number of column names to compare 
		searchCols (in ) - array of column names to compare 
    		minVals   (in ) - Array of column minimum values.
    		maxVals   (in ) - Array of column maximum values.
		maxRows   (in ) - Max number of rows to return.
		filename  (in ) - If not null, write results to this 
				  file.
		numFound  (out) - Number of objects found.
   		result (in/out) - Handle for accessing query results.
	Return value: 
		If successful, 0, otherwise 1.

acMore
        Return true if there would have been more rows available to
	the most recent query, but they were not returned because the
	maximum row (maxRows argument) limit was reached.

    	Arguments:
		handle    (in ) - catalog handle
	Return value: 
		1 if more rows were available, otherwise 0.

acNumCols
        Return the number of columns in the catalog.

    	Arguments:
		handle    (in ) - catalog handle
	Return value: 
		the number of columns in the catalog

acColName
        Return the name of the given column in the catalog, or NULL if
	there is no such column.

    	Arguments:
		handle    (in ) - catalog handle
		col       (in ) - column index (0..n)
	Return value: 
		column name of NULL if none

acColIndex
	Return the column index for the given column name, or -1 if
	there is no such column.

    	Arguments:
		handle    (in ) - catalog handle
		name      (in ) - column name
	Return value: 
		column index

acGetError
	Return the text of the most recent error message reported by
	the catalog routines.
 
   	Arguments:
		none
	Return value: 
		pointer to error text (a static buffer)

acGetErrorCode
	Return the error code from the most recent error message. This is
	one of the codes defined in <sys/errno.h>, for example: EINVAL for
	an invalid argument value.
 
   	Arguments:
		none
	Return value: 
		error code value


ACCESSING CATALOG QUERY RESULTS
The following routines operate on the AcResult object returned from
the query routines:

acrNumRows
	Return the number of result rows.

   	Arguments:
		handle    (in ) - query result handle
	Return value: 
		number of rows in result

acrNumCols
	Return the number of result columns.

   	Arguments:
		handle    (in ) - query result handle
	Return value: 
		number of columns in result

acrColNames
	Return a pointer to an array of result column names.
 
   	Arguments:
		handle    (in ) - query result handle
	Return value: 
		array of column names

acrGetString
acrGetInt
acrGetDouble
acrGetFloat
acrGetShort
acrGetChar
	Get result values by row and column index. 
	Note: there are various versions for different data types and
  	parameters.  All return 0 for success and set the last
  	argument value or return 1 for error.

   	Arguments:
		handle    (in ) - query result handle
		row       (in ) - row index
		col       (in ) - column index
		value  (in/out) - address of variable to hold value
	Return value: 
		0 for success, otherwise 1 for error.

acrGetNString
acrGetNInt
acrGetNDouble
acrGetNFloat
acrGetNShort
acrGetNChar
	Get result values by row and column name.
	Note: there are various versions for different data types and
  	parameters.  All return 0 for success and set the last
  	argument value or return 1 for error.

   	Arguments:
		handle    (in ) - query result handle
		row       (in ) - row index
		col       (in ) - column name
		value  (in/out) - address of variable to hold value
	Return value: 
		0 for success, otherwise 1 for error.

acrGetWC
	Get the position columns (RA and DEC) from the given result
	row and return success (0), otherwise error (1).

   	Arguments:
		handle    (in ) - query result handle
		row       (in ) - row index
		pos    (in/out) - address of WC object to hold coords
	Return value: 
		0 for success, otherwise 1 for error.

acrColIndex
	Return the result column index for the given result column
	name.

   	Arguments:
		handle    (in ) - query result handle
		colName   (in ) - name of column
	Return value: 
		column index or -1 for error.

acrDelete
	Delete the result object (free the memory).

SEE ALSO
AstroCatalog, TclAstroCat(3C++)
----------------------------------------------------------------------

