A catalog is opened with the static member function open :
AstroCatalog* cat = AstroCatalog::open(catalogName); if (!cat) { error(...); }
The catalog name may be either the long name or the short name , as defined in the catalog config file. The return value from the call to open is a pointer to an AstroCatalog object allocated for the given catalog. It should be deleted with the C++ delete operator when no longer needed.
If the argument passed to AstroCatalog ::open is the name of a file, the return value will point to a subclass of AstroCatalog called LocalCatalog , which works with local catalog files, but otherwise has the same basic interface:
AstroCatalog* cat = AstroCatalog::open(fileName); if (!cat) { error(...); }
For TCS catalogs 1 , the calling sequence is similar:
TcsCatalog* cat = TcsCatalog::open(catalogName);
or for local catalogs, if the argument is a file name, the return value points to a derived class of TcsCatalog called TcsLocaCatalog , which is specialized in local TCS catalog files.
The tree below illustrates the class hierarchy of the basic catalog access classes mentioned above:
There are a number of methods defined in the catalog classes for making queries. The main method is AstroCatalog::query . To use it, you first create an AstroQuery(3) object to represent the query and pass it, along with some other arguments, to the query method:
WorldCoords pos(3, 19, 48, 41, 30, 39); char* filename = NULL; AstroQuery q; q.pos(pos); q.radius(0, 10); q.maxRows(10); AstroObject* result = NULL; int numRows = cat->query(q, filename, result);
The AstroQuery object holds the query parameters. Any fields that are not specified are taken to be null and are not used in the query. In the example above, the WorldCoords class (see WorldCoords(3) in the astrotcl package) was used to create the center position argument as 3:19:48 +41:30:39 and a radius range was specified for the query. The table below lists all of the possible query parameters. In most cases, these are the names of two AstroQuery methods - one to set the value (with 1 argument) and another to get the value (with no arguments).
The actual query is made by the query method, which takes the AstroQuery object and an optional filename , does the query and returns the number of objects found. On success, the last parameter, result , is filled with the results of the query.
The QueryResult(3) class represents the result of a query and provides methods to get the column names and the value at a given row and column. As an example, the following code would print out the result of the query:
char* value; for (i = 0; i < result.numRows(); i++) for (j = 0; i < result.numCols(); j++) { if (result->get(i, j, value) == 0) cout << "row: " << i << ", col: " << j << ": " << value << endl; else error(...); } }
In this case, the column value was declared as string, however, there are also overloaded methods that extract result values as ints , shorts , floats , doubles , and also as world coordinates (class WorldCoords ) in a given format and equinox.
The following table lists some of the public methods in class QueryResult (and its base class TabTable ) for accessing the results of a query.
A number of QueryResult methods were not listed here because they are only used to implement local catalogs and are not normally needed otherwise.
For the TcsCatalog(3) class, the columns of the result are fixed, so there is no need to access them as strings. In this case, the call to the query method should pass an object of type TcsQueryResult(3) rather than its parent class QueryResult(3) . The TcsQueryResult class extends the QueryResult class by adding a method to access rows as objects.
TcsQueryResult result; int num_results = cat->query(q, NULL, result);
Then you can access the query result rows as objects, as in the following example:
TcsCatalogObject obj; // holds data for one row for (int row = 0; row < num_results; row++) { if (result.getObj(row, obj) != 0) cout << "row " << row << ": ERROR\n"; else cout << obj << endl; }
For TCS catalogs, replace the get(row, ...) methods with the following:
|
Put the contents of the given query result row in the given object of type class TcsCatalogObject. |
A Tcs catalog row always contains the following columns (any missing columns are set to a predefined null value):
|
Coordinate type as "M" for mean or "A" for apparent character |
||
A number of other methods are less generic, but were defined as a convenience for common queries 2 . For example,
cat->GetDescription(numCols, colNames);
sets the parameters to the number of columns in the catalog and the column names. If you have an object Id, you can retrieve the object with the following call:
status = cat->getObject(id, numCols, colNames, result);
You pass in the object id and the names of the columns you want and get back an array of column values (as strings). To perform a rectangular area query, specifying two points, you can call the following method:
status = cat->getArea(numCols, colNames, pos1, pos2, mag1, mag2, maxRows, filename, numFound, result);
If filename is specified, the result is also copied to the given file. In any case, you can access the result via the result argument, which is filled with the data on return. A circular search, where you specify a center point and one or two radius values, can be made as follows:
status = cat->circularSearch(numCols, colNames, pos, radius1, radius2, mag1, mag2, maxRows,filename, numFound, result);
Again, the results are written to the given file, if specified and to the given result object. To get the closest star or object to a given world coordinate point, you can call this method:
status = cat->searchClosestStar(numCols, colNames, pos, mag1, mag2, result);
In this case, the result only represents a single object or row. The following table summarizes the public methods of the AstroCatalog class:
Please send questions or comments to abrighto@eso.org@eso.org.
Copyright © 1998 ESO - European Southern Observatory