3.3.1 Information Catalogs in C

To use the C interface to access an information catalog, you should first include the header file:

The return value from acOpen is a handle that can be used in further calls to refer to the catalog. The catalog name should be one of the valid names listed in the catalog config file 1 . When you are done with the catalog, you can close it and free any resources used by with the acClose routine:

The above call passes the catalog handle as the first argument, as always. The next arguments are set by acGetDescription to the number of columns in the catalog and an array of column names. The return value here, as for most of the routines defined in the C interface, is 0 for success and 1 for error. If an error occurs, you can get the text of the error message with a call to acGetError :

A number of routines are defined for the various different types of catalog queries. If you already have an object Id from a previous query, this call will get the attributes of the object given by the Id:

The input arguments specify the catalog handle (cat ), object Id (string value) and an array of column names (of length numCols ) for the columns that should be returned. The return argument (result ) is a handle, similar to the catalog handle, that can be used to access the results 2 of the query. Routines are defined that operate on the query result to extract row and column values in various formats and give other information about the result, such as the result column names, number of rows and columns, etc (see below for more).

To get a list of all of the stars in a given area, marked by two world coordinate points, the following routine is defined:

As in the previous routine, the first three arguments specify the catalog handle, the number of columns and an array of columns names for the columns that should be returned by the query. The next four arguments specify the world coordinates of the two corner points of the area to be searched. The two magnitude arguments, mag0 and mag1 , are optional and can be set to 0.0 if not needed. Otherwise, they specify the min and maximum magnitude for the search. The maxRows argument limits the number of rows returned by the query. The acMore () routine can be called to determine if there would be more objects matching the query. If filename is not NULL, the results of the query are written to the given file, otherwise, the results are returned in the last argument.

Other query routines are: acCircularSearch and acSearchClosestStar , with a similar interface:

In this case, one world coordinate position and two radius values are specified for a circular search. The objects returned will be a distance between radius0 and radius1 from the center position. If mag0 and mag1 are not null (0.0), they are taken as the min and max magnitude. The rest of the arguments are the same as for acGetArea ().

Here you specify one world coordinate point and again the min and max magnitude (or 0.0, to ignore) and the return value is the handle for accessing the query result.

The following table summarizes the C routines for querying information catalogs:

Routine	Description
`acOpen`	Open a catalog and return a handle for it.
`acClose`	Close the catalog and free any resources used by it.
`acGetDescription`	Return a description of the catalog columns.
`acGetObject`	Return the column values for a given object Id.
`acCircularSearch`	Return a table of objects in a given circular area.
`acSearchClosestStar`	Return the column values for the closest object to a point.
`acGetArea`	Return a table of objects found in a given rectangular area.
`acGetError`	Return the text of the most recent error message.
`acGetErrorCode`	Return the error code from the most recent error message (a value from <errno.h>).
`acMore`	Return true if there were more than nrows rows available.
`acNumCols`	Return the number of columns in the catalog.
`acColName`	Return the column name given the index.
`acColIndex`	Return the index for a given column name.
`acIsNumeric`	Return true if the given column is numeric.

Accessing Query Results

The last argument to the catalog query routines is a handle of type AcResult . Routines are defined to access the query result by specifying a row and column index or column name and a pointer to a variable to hold the column value. For example, to print out the query results:

 
for (i = 0; i < numRows, i++) { 
    for (j = 0; j < numCols; j++) { 
        char* s; 
        if (acrGetString(result, i, j, &s) == 0) 
            printf("row %d, col %d: %s\n", i, j, s); 
        else  
            error(...); 
    } 
}

In this case, we treated all of the items as strings. Routines are also defined to access row,column values as int, short, char, float, double and world coordinates. To get the value for the column "mag " in a given row:

 
double d; 
if (acrGetNDouble(result, row, "mag", &d) == 0) {/* OK ...*/}

To get a world coordinate position, you can use the following:

 
WC pos; 
acrGetWC(result, row, &pos);

Where WC is a structure (described in the previous section) that represents world coordinates.

There are also routines to get the names of the result columns as well as the number of rows and columns in the result. The following table summarizes the routines for accessing query results:

Routine	Description
`acrNumRows`	Return the number of result rows.
`acrNumCols`	Return the number of result columns.
`acrColNames`	Return a pointer to an array of result 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.
`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.
`acrGetWC`	If the result contains a world coordinate position (fields ra and dec), get it and return success (0), otherwise error (1).
`acrColIndex`	Return the result column index for the given result column name.
`acrDelete`	Delete the result object (free the memory).

1. The C++ interface has methods to get a list of catalogs and catalog attributes. This is currently missing in the C interface.

2. Note that memory is allocated for the query results and it is the caller's responsibility to delete the object with the acrDelete() routine when no longer needed.