#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);
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.
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.
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.
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).
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).
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 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.
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).
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.
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
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).
Please send questions or comments to abrighto@eso.org@eso.org.
Copyright © 1998 ESO - European Southern Observatory