dbspr1row

Description

Place one row of server query results into a buffer.

Syntax

RETCODE dbspr1row(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 dbspr1row results.

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

dbspr1row fills a programmer-supplied buffer with a null-terminated character string containing one server query results row.

dbspr1row is useful when displaying data for debugging and writing applications that scroll data displays.

dbspr1row gives programmers greater control over data display than dbprrow. dbprrow always writes its output to the display device, while dbspr1row writes its output to a buffer, which the programmer may then display at whatever time or location is desired.

To pad results data to its maximum converted length, specify a pad character through the DB-Library option DBPRPAD. The pad character will be appended to each column’s data. 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 converted column’s data 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 new line (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 dbspr1row can be determined by calling dbspr1rowlen.
The format of results rows returned by dbspr1row is determined by the SQL query. dbspr1row makes no attempt to format the data beyond converting it to printable characters, padding the columns as necessary, and adding the column and line separators.
To make the best use of dbspr1row, application programs should call it once for every successful call to dbnextrow.

The following code fragment illustrates the use of dbspr1row:

                 char     mybuffer[2000]; 
 
                 while (dbnextrow(dbproc) != NO_MORE_ROWS) 
                 { 
                     dbspr1row(dbproc, mybuffer,sizeof(mybuffer)); 
                     fprintf( stdout, "\n%s", mybuffer); 
                   }

The following code fragment shows the use of the DBPRPAD and DBPRCOLSEP options:

 char     mybuffer[2000];

/*

 ** Specify the pad and column separator

 ** characters */

 /* Pad = 0x2A */

 dbsetopt(dbproc, DBPRPAD, "*", DBPADON);

 /* Col. sep. = 0x2C20 */

 dbsetopt(dbproc, DBPRCOLSEP, ", ", 2);

 while (dbnextrow(dbproc) != NO_MORE_ROWS)

      dbspr1row(dbproc, mybuffer,

           sizeof(mybuffer) );

      fprintf( stdout, "\n%s", mybuffer);

 /* Turn padding off */

 dbsetopt(dbproc, DBPRPAD, SS, DBPADOFF );

 /* Revert to default */

 dbsetopt(dbproc, DBPRCOLSEP, RS, -1 );