The HEASARC Database System

Utility Applications

HDBfilter

The HDBfilter application provides capabilities to process the HDBmc client application's SQL query results. It can reformat the results into either a name=value pair or a compressed table format, convert Right Ascension and Declination values to degrees, convert Class value to ASCII representation, precess equatorial coordinates, and perform a cone search. It verifies 10 optional and 1 required command line arguments: layout (optional), equinox year (optional), Right Ascension name (optional), Declination name (optional), Class name (optional), Right Ascension mode (optional), Declination mode (optional), Class mode (optional), source and destination equinox years for precession (optional) , Right Ascension, Declination, and radius for cone search (optional), and input file specification; sequentially reads the contents of the input file; calls the load_table function to load the information into a dynamically allocated table array (for table layout); calls the ra_str2deg, ra_deg2hms, dec_str2deg, and dec_deg2dms AUTIL functions to perform necessary format conversions of Right Ascension and Declination values; calls the slaPreces SLA routine for coordinate precession; calls the slaDsep SLA routine to determine the distance between two points on a sphere (for cone search); calls the print_buffer routine to write the results to standard output; and frees the dynamically allocated table array via a call to the free_table routine (for table layout). For various string manipulations, the partok, strcnvprnt, and strtrm UTIL routines are used. The table format is compressed, to prevent the display of needlessly wide columns. The column width is set to that of the longest value present.

Command arguments:

        HDBfilter [-layout=pair|table] [-raname=name|ra] [-decname=name|dec]
                    [-ra=hms|deg] [-dec=dms|deg] [-precess=from_year,to_year]
                    [-cone=ra,dec,radius] file

Options:

-layout=pair|table

Converts the data to either name=value pair (pair) or table (table) format. Default is table.

-equinox=eq

Appends the specificed equinox year to ra and dec parameter headers.

-raname=name|ra

Specifies the right ascension parameter name. Default is ra.

-decname=name|dec

Specifies the declination parameter name. Default is dec.

-classname=name|class

Specifies the class parameter name. Default is class.

-ra=hms|deg

Converts right ascension data to either hh mm ss (hms) or degrees (deg) format. Default is degrees.

-dec=dms|deg

Converts declination data to either dd mm ss (dms) or degrees (deg) format. Default is degrees.

-class=ascii|integer

Converts class to either integer or ASCII. Default is integer.

-precess=from_year,to_year

Performs coordinate precession of right ascension and declination data.

-cone=ra,dec,radius Filters data based on cone search. Values for ra and dec are in degrees and radius in arc minutes.

Either a filename or a minus sign (-) can be specified for the file argument (useful for pipe). In either case, the contents of the data must be in SQL table format.

Examples:

HDBfilter layout=pair -ra=hms -dec=dms -precess=1950,2000 test.table

HDBmc "sql=select * from heasarc_ascapublic where name like 'ABELL%' | HDBfilter -

The following example executes HDBmc client to query the heasarc_ariel5 table and pipes the output of the query to the HDBfilter application with all options specified:

% HDBmc "sql=select name,ra,dec,class from heasarc_ariel5" | HDBfilter -layout=table -equinox=2000 -raname=ra -decname=dec -classname=class -ra=hms -dec=dms -class=ascii -precess=1950,2000 -cone=0,0,60 -

+-------+----------+-----------+------------+
|name   |ra(2000)  |dec(2000)  |class       |
+-------+----------+-----------+------------+
|TRA X-1|00 02 33.7|+00 16 42.2|UNIDENTIFIED|#90
|SRC_158|00 02 33.7|+00 16 42.2|UNIDENTIFIED|#138
+-------+----------+-----------+------------+
(2 rows)

HDBrect

The HDBrect application calculates the minimum and maximum values of Right Ascension and Declination values for a rectangle that encloses a sphere. It verifies 1 optional and 4 required command line arguments: mode (optional), equinox year, longitude of center, latitude of center, and radius; calls the slaGaleq SLA routine to convert the input coordinates from galactic to equatorial or the slaEcleq SLA routine to convert the input coordinates from ecliptic to equatorial, depending on the optional mode argument; calls the slaPreces SLA routine to perform precession of coordinates; calls the sphrect AUTIL routine to calculate the rectangle; and prints the results in degrees to standard output.

Command arguments:

HDBrect [-mode=galactic|ecliptic|equatorial] e l b r

Option

-mode=galactic|ecliptic|equatorial

Performs either galactic to equatorial (galactic) or ecliptic to equatorial (ecliptic) conversion. The default is equatorial.

Arguments:

• e Equinox year of coordinates.
• l Longitude of center in degrees.
• b Latitude of center in degrees.
• r Radius in arc minutes.

Example:

HDBrect -mode=galactic 1950 18.94 -73.70 60

HDBprec

The HDBprec application performs precession of equatorial coordinates. It verifies 4 command line arguments: source equinox year, destination equinox year, Right Ascension, and Declination; calls the slaPreces SLA routine to precess the coordinates; and writes the results in degrees to standard output. The verification of Right Ascension and Declination values are via calls to the ra_str2deg and dec_str2deg AUTIL functions, respectively.

Command arguments:

HDBprec eq0 eq1 ra dec

Arguments:

• eq0 Equinox year of coordinates (from).
• eq1 Equinox year of coordinates (to).
• ra Right Ascension in degrees.
• dec Declination in degrees.

Example:

HDBprec 1950 2000 18.94 -73.70