dbsprhead

Description

Place the server query results header into a buffer.

Syntax

RETCODE dbsprhead(dbproc, buffer, buf_len)
 
DBPROCESS     *dbproc;
char                    *buffer;
DBINT                  buf_len;

Parameters

dbproc: A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server.

buffer: A pointer to a character buffer to contain the query results header.

buf_len: The length of buffer, including its null terminator.

Returns

SUCCEED or FAIL.

If an error occurs, the contents of *buffer are undefined.

Usage

dbsprhead fills a programmer-supplied buffer with a null-terminated character string containing the header for the current set of query results. The header consists of the column names. The sequence of the column names matches that of the output of dbspr1row.

dbsprhead is useful when printing data for debugging, and when scrolling data displays.

To pad each column name to its maximum converted length, specify a pad character using the DB-Library option DBPRPAD. The pad character will be appended to each column’s name. The maximum converted column length is equal to the longest possible string that could be the column’s displayable data, or the length of the column’s name, whichever is greater. See Options for more details on the DBPRPAD option.
You can specify the column separator string using the DB-Library option DBPRCOLSEP. The column separator will be added to the end of each column name except the last. The default separator is an ASCII 0x20 (space). See Options for more details on the DBPRCOLSEP option.
You can specify the maximum number of characters to be placed on one line using the DB-Library option DBPRLINELEN.

You can specify the line separator string using the DB-Library option DBPRLINESEP. The default line separator is a newline (ASCII 0x0a or 0x0d, depending on the host system). See Options for more details on the DBPRLINELEN and DBPRLINESEP options.
The length of the buffer required by dbsprhead can be determined by calling dbspr1rowlen.
To make the best use of dbsprhead, application programs should call it once for every successful call to dbresults.

The following code fragment illustrates the use of dbsprhead:

dbcmd(dbproc, "select * from sysdatabases");

dbcmd(dbproc, " order by name");

dbcmd(dbproc, " compute max(crdate) by name");

dbsqlexec(dbproc);

dbresults(dbproc);

dbsprhead(dbproc, buffer, sizeof(buffer));

printf("%s\n", buffer);