Ns_Db0or1Row

Overview

Execute an SQL statement that must return £ 1 row

Syntax

    Ns_Set *Ns_Db0or1Row(
    	Ns_DbHandle *handle,
    	char        *sql,
    	int         *nrows
    );

Description

The Ns_Db0or1Row function sends the given SQL statement to the database and immediately processes the results. On zero rows, a newly allocated Ns_Set with its keys set to the column names and values uninitialized is returned and nrows is set to 0. On one row, a newly allocated Ns_Set containing the values is returned and nrows is set to 1. You must eventually free this row using Ns_SetFree.

Note that an SQL select statement that does not return a row is different from an SQL DML statement that does not return a row but modifies the database. In the former case, Ns_Db0or1Row still returns a newly allocated Ns_Set with the column names as the field key names of the rows that would have been returned had any of the rows in the database matched the select criteria. In the latter case, Ns_Db0or1Row returns an error.

If the SQL statement returns more than one row or some database error occurs, Ns_Db0or1Row returns NULL. Detailed error messages may have accumulated in an internal buffer in the Ns_DbHandle. These errors can be conveyed back to the user through the Ns_DbReturnError function.

Example

    Ns_Set *row;
    int nrows;
    Ns_DbHandle *handle;
    if ((handle = Ns_DbPoolGetHandle("aPoolName")) != NULL) {
    	row = Ns_Db0or1Row(handle, "select aName from aTable",
    							&nrows);
    	if (row != NULL && nrows == 1) {
    		char *value;
    		value = Ns_SetGet(row, "aName");
    		/* use `value' here */
    		Ns_SetFree(row);
    	}
    } 
    

Top of Page

Copyright © 1996 America Online, Inc.