The HEASARC Database System

Client-Server Software

This section describes the internals of the HDBmc/HDBmcs metadata/catalog client/server software, the HDBdp/HDBdps data products search client/server, and the HDBcone/HDBcones cone search client/server software. Note that the HDBdp/HDBdps and HDBcone/HDBcones clients/servers are no longer supported and their internal usage has been discontinued. The HDBmc/HDBmcs client/server is still supported and used internally, but it cannot be used to access the HEASARC DBMS by external users.

HDBmc/HDBmcs

The HDBmc/HDBmcs client/server software provides the metadata/catalog query interface to the DBMS. This system, written in the C programming language, uses the CSIO (TCP/IP Client/Server Primitive Data Input/Output) software library for transparent task-to-task communications and is compatible with the Intel/Linux, AXP/OSF1, MIPS/Ultrix, and SPARC/SunOS platforms. A VAX/VMS and AXP/VMS compatible version of the client application is also available. The following sections describe the internals of the HDBmc/HDBmcs system.

HDBmc

The HDBmc client application calls the csioc_connect CSIO function to establish connection with the server; calls the csioc_output CSIO function to send the user-specified command to the server; checks the status returned from the server with a call to the csioc_status CSIO function; executes the loop to call the csioc_input CSIO function to read and write results to standard output; and calls the csioc_disconnect CSIO routine to terminate the connection with the server. Any error message returned from the server via a call to the csioc_getstatus CSIO function is printed to standard output.

The following metadata/catalog commands are supported:

table=table_name[,...]              returns table information in name=value
                                    format (multiple table names and wildcards
                                    are supported).
                                    Example

parameter=table_name[,...]          returns parameter information about a
                                    table in name=value format (multiple table
                                    names and wildcards are supported)
	                            Example

observatory=observatory_name[,...]  returns table_name and observatory_name in
                                    name=value format for the specified
                                    observatory_name (multiple observatory
                                    names and wildcards are supported)

sql=SELECT...                       returns the output of an SQL SELECT
                                    statement in Ingres DBMS SQL Terminal
                                    Monitor table format. Example:
                                    "sql=select name, ra, dec from heasarc_wgacat"

HDBmcs

The following sections provide the internals of the HDBmcs server.

HDBmcs_main

This is the main entry point of the metadata/catalog server. It calls the csios_init CSIO function to establish the server environment, executes the loop to call the HDBmcs_parse function to read and parse commands from the client, and dispatches them to appropriate action routines: HDBmcs_table, HDBmcs_parameter, HDBmcs_observatory, and HDBmcs_sql. A call to the csios_exit CSIO routine terminates the server.

HDBmcs_parse

The HDBmcs_parse function is the server's parser. It calls the csios_input CSIO function to read a command buffer from the client, calls the strcnvprnt and strtrm UTIL routines to perform necessary string format conversions, extracts the command verb from the buffer, and compares it against the statically declared command structure. If the command verb is verified, this function returns a pointer to an action routine as an argument - HDBmcs_main executes the action routine by simply dereferencing the returned pointer to a routine. Otherwise, it sends an error message to the client via a call to the csios_error CSIO routine.

HDBmcs_table

The HDBmcs_table action routine generates SQL SELECT statements to query the ZZGEN and ZZEXT metadata tables based on table_name column and returns the results to the client in name=value format. It calls the partok, strrpl, strloc, and strtrm UTIL routines along with the HDBmcs_buffer function to create dynamically allocated SQL SELECT statement buffers, calls the HDBmcs_dbopen function to open and execute the first query statement (simple query of the ZZGEN table), executes a loop to call the HDBmcs_dbread function to sequentially read the query results and load them into a dynamically allocated table descriptor linked-list data structure via calls to HDBmcs_alloctd function, and calls HDBmcs_dbclose routine to close the database and terminate the query session. If the first query is successful, a second query is executed (two table join query of the ZZGEN and ZZEXT tables), following the same procedure as the first. Results are then constructed and sent to the client with calls to the csios_signal and csios_output CSIO functions by traversing the table descriptor linked-list. Finally, the table descriptor linked-list is freed with a call to HDBmcs_freetd routine. If any error is encountered, the routine sends an error message to the client with a call to the csios_error CSIO routine.

HDBmcs_parameter

The HDBmcs_parameter action routine generates SQL SELECT statements to query the ZZPAR and ZZREL metadata tables based on table_name column and returns the results to the client in name=value format. It calls the partok, strrpl, strloc, and strtrm UTIL routines along with the HDBmcs_buffer function to create dynamically allocated SQL SELECT statement buffers, calls the HDBmcs_dbopen function to open and execute the first query statement (simple query of the ZZPAR table), executes a loop to call the HDBmcs_dbread function to sequentially read the query results and load them into a dynamically allocated parameter descriptor linked-list data structure via calls to the HDBmcs_allocpd function, and calls the HDBmcs_dbclose routine to close the database and terminate the query session. If the first query is successful, a second query is executed (two table join query of the ZZPAR and ZZREL tables), following the same procedure as the first. Results are then constructed and sent to the client with calls to the csios_signal and csios_output CSIO functions by traversing the parameter descriptor linked-list. Finally, the parameter descriptor linked-list is freed with a call to the HDBmcs_freepd routine. If any error is encountered, the routine sends an error message to the client with a call to the csios_error CSIO routine.

HDBmcs_observatory

The HDBmcs_observatory action routine generates an SQL SELECT statement to query the ZZEXT metadata table based on "observatory_name" parameter_name column and returns the results to the client in name=value format. It calls the partok, strrpl, strupc, and strtrm UTIL routines along with the HDBmcs_buffer function to create a dynamically allocated SQL SELECT statement buffer, calls the HDBmcs_dbopen function to open and execute the query statement, executes a loop to call the HDBmcs_dbread function to sequentially read the query results and load them into a dynamically allocated table descriptor linked-list data structure via calls to the HDBmcs_alloctd function, and calls the HDBmcs_dbclose routine to close the database and terminate the query session. Results are then constructed and sent to the client with calls to the csios_signal and csios_output CSIO functions by traversing the table descriptor linked-list. Finally, the table descriptor linked-list is freed with a call to the HDBmcs_freetd routine. If any error is encountered, the routine sends an error message to the client with a call to the csios_error CSIO routine.

HDBmcs_sql

The HDBmcs_sql action routine executes the SQL SELECT query statement and returns the query results to the client. It verifies the statement, calls the HDBmcs_dbopen function to open and execute the statement, executes a loop to call the HDBmcs_dbread function to sequentially read the query results and send them to the client via calls to the csios_signal and csios_output CSIO functions, and calls the HDBmcs_dbclose routine to close the database and terminate the query session. If any error is encountered, the routine sends an error message to the client with a call to the csios_error CSIO routine.

HDBmcs_buffer

The HDBmcs_buffer utility routine copies or concatenates the contents of a NULL-terminated character string buffer to a dynamically allocated buffer. If any error is encountered, the routine sends an error message to the client with a call to the csios_error CSIO routine.

HDBmcs_dbopen

The HDBmcs_dbopen function opens the database and executes an SQL statement via the Ingres or Sybase SQL Terminal Monitor. It calls the HDBmcs_dbclose routine to close any opened database session, calls the strrpl and strchrcnt UTIL routines along with the HDBmcs_buffer routine to create a dynamically allocated SQL statement buffer, creates an interprocess, bidirectional socket, and forks a child process. The child process then invokes the vendor-supplied DBMS SQL query tool, and the parent process sends the SQL statement to the child process.

HDBmcs_dbread

The HDBmcs_dbread function reads a buffer from a previously opened database session. It verifies that a database session exists, reads a buffer from the socket (child process), and calls the strcnvprnt and strtrm UTIL routines to perform necessary string format conversions.

HDBmcs_dbclose

The HDBmcs_dbclose routine closes a database session. It verifies that a database session exists and ends the session (child process termination). This routine calls no other HDBmcs, UTIL, or CSIO routines.

HDBmcs_alloctd

The HDBmcs_alloctd function loads information into a dynamically allocated table descriptor linked-list data structure. If the table descriptor passed in as an argument to the function is NULL, a new descriptor is allocated, and contents of the table_name, name, and value argument variables are loaded into the descriptor with a call to the HDBmcs_allocnv function. Otherwise, it calls the HDBmcs_allocnv function if the table_name is identical to the current descriptor's table_name, or the HDBmcs_alloctd function (recursion) if not. If any error is encountered, the routine sends an error message to the client with a call to the csios_error CSIO routine.

HDBmcs_freetd

The HDBmcs_freetd routine frees a dynamically allocated table descriptor linked-list data structure. It traverses the linked-list and frees both the descriptor and the name/value descriptor linked-list data structure (HDBmcs_freenv routine call).

HDBmcs_allocpd

The HDBmcs_allocpd function loads information into a dynamically allocated parameter descriptor linked-list data structure. If the parameter descriptor passed in as an argument to the function is NULL, a new descriptor is allocated, and the contents of the table_name, parameter_name, name, and value argument variables are loaded into the descriptor with a call to the HDBmcs_allocnv function. Otherwise, it calls the HDBmcs_allocnv function if the table_name and parameter_name are identical to the current descriptor's table_name and parameter_name, or the HDBmcs_allocpd function (recursion) if not. If any error is encountered, the routine sends an error message to the client with a call to the csios_error CSIO routine.

HDBmcs_freepd

The HDBmcs_freepd routine frees a dynamically allocated parameter descriptor linked-list data structure. It traverses the linked-list and frees both the descriptor and the name/value descriptor linked-list data structure (HDBmcs_freenv routine call).

HDBmcs_allocnv

The HDBmcs_allocnv function loads information into a dynamically allocated name/value descriptor linked-list data structure. If the name/value descriptor passed in as an argument to the function is NULL, a new descriptor is allocated, and contents of the name and value argument variables are loaded into the descriptor. Otherwise, it calls the HDBmcs_allocnv function (recursion). If any error is encountered, the routine sends an error message to the client with a call to the csios_error CSIO routine.

HDBmcs_freenv

The HDBmcs_freenv routine frees a dynamically allocated name/value descriptor linked-list data structure. This routine calls no other HDBmcs, UTIL, or CSIO routines.

HDBdp/HDBdps

The HDBdp/HDBdps client/server software is no longer supported by the HEASARC. It provided an interface to query the DBMS for data products. This system, written in the C programming language, used the CSIO software library for transparent task-to-task communications and is compatible with the AXP/OSF, MIPS/Ultrix, and SPARC/SunOS platforms. A VAX/VMS and AXP/VMS compatible version of the client application is also available. The source code is still available for download. The following sections provide the internals of the system.

HDBdp

The HDBdp client application calls the csioc_connect CSIO function to establish connection with the server; calls the csioc_output CSIO function to send the user-specified command to the server; checks the status returned from the server with a call to the csioc_status CSIO function; executes the loop to call the csioc_input CSIO function to read and write results to standard output; and calls the csioc_disconnect CSIO routine to terminate the connection with the server. Any error message returned from the server via a call to the csioc_getstatus CSIO function is printed to standard output.

The command argument is a standard SQL SELECT statement. The application accepts the SQL select statement and returns the data in the current format: record_number,qualifier,type,format,filename,description.

        HDBdp "select ..."

            Example:

                HDBDP "select * from heasarc_ascapublic where name like
                      'ABELL%'"

HDBdps

The HDBdps server calls the csios_init CSIO function to establish the server environment, calls the csios_input CSIO function to read an SQL SELECT statement buffer from the client, parses the buffer into tokens, opens the ZZDP data products metadata table file, and loads the information for the specified table into dynamically allocated data product and data column linked-list data structures with calls to the hdballocdp and hdballocdc functions. It then constructs the SQL SELECT statement; executes the HDBmc client application via a pipe; and executes a loop to sequentially read the query results, call the hdbfilename function to construct and verify the data product filenames, and send results to the client with calls to the csios_signal and csios_output CSIO functions. Finally, both the data product and data column linked-list data structures are freed via calls to the hdbfreedp and hdbfreedc routines, and the csios_exit CSIO routine is called to terminate the server. If any error is encountered, the server sends an error message to the client via a call to the csios_exit CSIO routine. For various string manipulations, the partok, strtrm, and strcmpw UTIL routines are used.

HDBcone/HDBcones

The HDBcone/HDBcones client/server software is no longer supported by the HEASARC. It provided a cone search interface to the DBMS. This system, written in the C programming language, uses the CSIO software library for transparent task-to-task communications and is compatible with the AXP/OSF, MIPS/Ultrix, and SPARC/SunOS platforms. A VAX/VMS and AXP/VMS compatible version of the client application is also available. The source code is still available for download. The following sections provide the internals of the system.

HDBcone

The HDBcone client application calls the csioc_connect CSIO function to establish connection with the server; calls the csioc_output CSIO function to send the user-specified command to the server; checks the status returned from the server with a call to the csioc_status CSIO function; executes the loop to call the csioc_input CSIO function to read and write results to standard output; and calls the csioc_disconnect CSIO routine to terminate the connection with the server. Any error message returned from the server via a call to the csioc_getstatus CSIO function is printed to standard output.

The full command syntax for the HDBcone client (/heasarc/bin/HDBcone) is as follows:

        HDBcone table[,...] equinox ra dec {radius|-default}
                {column[,...]|-default} [file]

        If -default is specified for the radius, the server performs
        the search using the default cone search radius associated with
        the table.  Additionally, if -default is specified for the column
        list, the server returns data only for the default parameters for
        the table.  Here are couple of examples:

        Example 1:

                HDBcone "heasarc_*" 1950 19 -73 -default -default

                Directs the server to search all tables beginning with
                heasarc_ using default radius, and to return values for
                default columns.

        Example 2:

                HDBcone heasarc_me,heasarc_cma 2000 19 -73 60 name,ra,dec,class

                Directs the server to search heasarc_me and heasarc_cma tables
                using 60 arcmin radius, and to return values for name, ra, dec,
                and class columns.

        Returned data will be in compressed table format with right ascension
        and declination values in hh mm ss and dd mm ss formats, respectively,
        and class in ASCII.

HDBcones

The HDBcones server calls the csios_init CSIO function to establish the server environment, calls the csios_input CSIO function to read a command buffer from the client, and verifies the command. It then calls the HDBloadtd function (executes the HDBmc client application to query the DBMS for table and parameter metadata information) to dynamically allocate a table descriptor linked-list data structure; traverses the table descriptor linked-list to construct the SQL SELECT statement; executes the HDBmc client and HDBfilter utility applications via a pipe; and executes a loop to sequentially read and send the query results to the client via calls to the csios_signal and csios_output CSIO functions. The procedure for constructing the SQL SELECT statement involves calls to the HDBfindnv function to determine "equinox", "default_search_radius", "right_ascension", "declination", and "parameter_default" attribute information for the specified table; and calls to the slaPreces SLA and sphrect AUTIL routines for coordinate precession and rectangle calculation, respectively. Finally, the HDBfreetd routine is called to free the table descriptor linked-list, and the csios_exit CSIO routine is called to terminate the server. If any error is encountered, the server sends an error message to the client with a call to the csios_error CSIO routine. For various string manipulations, the partok, strtrm, and strchrcnt UTIL routines are used.