#Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ConnReturnInternalError Overview Return an "internal error" HTTP status line. Syntax int Ns_ConnReturnInternalError( Ns_Conn *conn ); Description Calls Ns_ConnReturnStatus or Ns_ConnReturnNotice with a status code of 500 to indicate that an internal error occurred. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ConnReturnNoResponse Overview Return a "no response" HTTP status line. Syntax int Ns_ConnReturnNoResponse( Ns_Conn *conn ); Description Calls Ns_ConnReturnStatus or Ns_ConnReturnNotice with a status code of 204 to indicate that the request requires no response. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ConnReturnNotFound Overview Return a "not found" HTTP status line. Syntax int Ns_ConnReturnNotFound( Ns_Conn *conn ); Description Calls Ns_ConnReturnStatus or Ns_ConnReturnNotice with a status code of 404 to indicate that the requested URL was not found on the server. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ConnReturnNotice Overview Return a short notice to a client Syntax int Ns_ConnReturnNotice( Ns_Conn *conn, int status, char *notice, char *html ); Description The Ns_ConnReturnNotice function returns to a client a simple HTML page with the given notice as the title of the page. The page includes the /NS/Asset/notice.gif image at the top of the page. If the html parameter is not NULL, it is added to the page after the notice. The HTML source can be arbitrarily long and should not contain the
or
begin or end tags; these tags will be added by Ns_ConnReturnNotice. AOLserver uses Ns_ConnReturnNotice extensively, to achieve a consistent look on the pages it automatically generates. Ns_ConnReturnNotice returns a status of NS_OK or NS_ERROR. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ConnReturnNotImplemented Overview Return a "not implemented" HTTP status line. Syntax int Ns_ConnReturnNotImplemented( Ns_Conn *conn ); Description Calls Ns_ConnReturnStatus or Ns_ConnReturnNotice with a status code of 500 to indicate that the request has not been implemented by the server. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ConnReturnNotModified Overview Return a "not modified" HTTP status line. Syntax int Ns_ConnReturnNotModified( Ns_Conn *conn ); Description Calls Ns_ConnReturnStatus or Ns_ConnReturnNotice with a status code of 304 to indicate that the requested data have not been modified since the time specified by the If-Modified-Since header sent by the client. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ConnReturnOk Overview Return an "OK" HTTP status line. Syntax int Ns_ConnReturnOk( Ns_Conn *conn ); Description Calls Ns_ConnReturnStatus or Ns_ConnReturnNotice with a status code of 200 to indicate that the request was successful. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ConnReturnOpenChannel Overview Write channel content to conn Syntax int Ns_ConnReturnOpenChannel ( Ns_Conn* conn, int status, char* type, Tcl_Channel chan, int len ); Description Write len bytes of an open Tcl channel out to the conn. Return HTTP status in status and Content-type in type. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ConnReturnOpenFd Overview Return a file to a client Syntax int Ns_ConnReturnOpenFile( Ns_Conn *conn, int status, char *type, int fd, int len ); Description The Ns_ConnReturnOpenFd function is the same as Ns_ConnReturnFile except that it takes an fd argument instead of a file name, and it requires an additional length argument. It returns the entire contents of the given file to the client. Ns_ConnReturnOpenFd returns a status of NS_OK or NS_ERROR. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ConnReturnOpenFile Overview Return a file to a client Syntax int Ns_ConnReturnOpenFile( Ns_Conn *conn, int status, char *type, FILE *fp, int len ); Description The Ns_ConnReturnOpenFile function is the same as Ns_ConnReturnFile except that it takes a FILE *fp argument instead of a file name, and it requires an additional length argument. It returns the entire contents of the given file to the client. Ns_ConnReturnOpenFile returns a status of NS_OK or NS_ERROR. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ConnReturnRedirect Overview Return an HTTP redirect response to a client Syntax int Ns_ConnReturnRedirect( Ns_Conn *conn, char *location ); Description The Ns_ConnReturnRedirect function returns a properly formatted HTTP redirect message for the given location. This causes the browser to seamlessly open the new location on behalf of the user. Ns_ConnReturnRedirect returns NS_OK or NS_ERROR. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ConnReturnStatus Overview Return a status message to a client Syntax int Ns_ConnReturnStatus( Ns_Conn *conn, int status ); Description The Ns_ConnReturnStatus function calls Ns_ConnSetRequiredHeaders with the given status and reason and then immediately calls Ns_ConnFlushHeaders. It can be used when only the status of the request must be returned to the client. The status is a standard error code such as 403 for access denied or 200 for OK. Returns NS_OK or NS_ERROR. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ConnReturnUnauthorized Overview Return an "unauthorized" HTTP status line. Syntax int Ns_ConnReturnUnauthorized( Ns_Conn *conn ); Description Calls Ns_ConnReturnStatus or Ns_ConnReturnNotice with a status code of 401 to indicate that the request did not include a valid Authorization header or the header did not specify an authorized user. The user will usually be prompted for a username/password after this status is returned. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ConnRunRequest Overview Execute procedure for method and URL pattern Syntax int Ns_ConnRunRequest( Ns_Conn *conn ); Description Locate and execute the procedure for the given method and URL pattern (in the conn->request). Returns a standard request procedure result, normally NS_OK. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ConnSendChannel Overview Send Tcl channel content to conn Syntax int Ns_ConnSendChannel ( Ns_Conn* conn, Tcl_Channel chan, int len ); Description Read len bytes from an open Tcl channel and write it out to the conn until EOF. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ConnSendDString Overview Write a DString to the conn Syntax int Ns_ConnSendDString( Ns_Conn *conn, Ns_DString *dsPtr ); Description Write out a DString to the conn. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ConnSendFd Overview Write file to connection content Syntax int Ns_ConnSendFd( Ns_Conn *conn, int fd, int len ); Description The Ns_ConnSendFd function writes len bytes from the file pointed to by fd to the connection. Ns_ConnSendFd returns the status NS_ERROR or NS_OK. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ConnSendFp Overview Write file to connection content Syntax int Ns_ConnSendFp( Ns_Conn *conn, FILE *fp, int len ); Description The Ns_ConnSendFp function writes len bytes from the file pointed to by fp to the connection. Ns_ConnSendFp returns the status NS_ERROR or NS_OK. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ConnServer Overview Return name of server Syntax char *Ns_ConnServer( Ns_Conn *conn ); Description The Ns_ConnServer function returns the name of the server associated with the connection. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ConnSetExpiresHeader Overview Return an "expires" header for the given time Syntax void Ns_ConnSetExpiresHeader( Ns_Conn *conn, char *httptime ); Description The Ns_ConnSetExpiresHeader formats and sends a header that will expire, using the time specified by the httptime string. You can use the Ns_HttpTime function to generate the time specification string. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ConnSetHeaders Overview Set the value for a header field Syntax void Ns_ConnSetHeaders( Ns_Conn *conn, char *field, char *value ); Description The Ns_ConnSetHeaders function sets the value of a field in the output headers, replacing an existing field/value pair. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ConnSetLastModifiedHeader Overview Return a last modified header using the given time Syntax void Ns_ConnSetLastModifiedHeader( Ns_Conn *conn, time_t *when ); Description The Ns_ConnSetLastModifiedHeader function formats and sends a Last-Modified header based on the given time. The time parameter is most often generated with the stat system call on an existing file. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ConnSetLengthHeader Overview Return a Content-Length header Syntax void Ns_ConnSetLengthHeader( Ns_Conn *conn, int len ); Description The Ns_ConnSetLengthHeader function formats and sends a Content-Length header for the given length. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ConnSetRequiredHeaders Overview Return the required HTTP headers Syntax void Ns_ConnSetRequiredHeaders( Ns_Conn *conn, char *contentType, int contentLength ); Description The Ns_ConnSetRequiredHeaders function writes the required headers of the HTTP response. If contentType is NULL, it defaults to 'text/html'. If contentLength is 0, no contentLength header will be written out. The Ns_ConnReturnStatus function can be used to return a status-only response to the client. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ConnSetTypeHeader Overview Return a Content-Type header Syntax void Ns_ConnSetTypeHeader( Ns_Conn *conn, char *type ); Description The Ns_ConnSetTypeHeader function formats and sends a Content-Type header for the given type. You can use the Ns_GuessMimeType() function to look up a Content-Type string for filename. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ConnWrite Overview Send data to a client Syntax int Ns_ConnWrite( Ns_Conn *conn, void *buf, int len ); Description The Ns_ConnWrite function attempts to write out the specified length of data from the given buffer to the client. It returns the number of bytes sent or -1 if there is an error. This function may write fewer than len bytes. Examples /* Write towrite bytes from buf. */ while (towrite > 0) { int nwrote; nwrote = Ns_ConnWrite(conn, buf, towrite); if (nwrote == -1) { /* ... handle error ... */ } buf += nwrote; towrite -= nwrote; } [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_CsDestroy Overview Destroy a critical section object Syntax void Ns_CsDestroy( Ns_Cs* ); Description Free the resources associated with the critical section. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_CsEnter Overview Enter a critical section Syntax void Ns_CsEnter( Ns_Cs *csPtr ); Description Enter the specified critical section. If the critical section is use by another thread, the current will block until it is no longer so. Note that critical sections are recursive and must be exited the same number of times as they were entered. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_CsInit Overview Initialize a critical section Syntax void Ns_CsInit( Ns_Cs *csPtr ); Description Initialize the specified critical section. It is recommended that you use a mutex instead of a critical section if possible. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_CsLeave Overview Leave a critical section Syntax void Ns_CsLeave( Ns_Cs *csPtr ); Description Leave the specified critical section. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_Ctime Overview Perform ctime_r Syntax char* Ns_Ctime ( const time_t* clock ); Description This function is a wrapper around ctime_r(3C). [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] 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. Examples 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); } } [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_Db1Row Overview Execute an SQL statement that must return one row Syntax Ns_Set *Ns_Db1Row( Ns_DbHandle *handle, char *sql ); Description The Ns_Db1Row function calls the Ns_Db0or1Row function with the given SQL statement. If Ns_Db0or1Row returns 1 row, Ns_Db1Row returns the newly allocated Ns_Set for the row. You must eventually free this row using Ns_SetFree. If NsDb0or1Row returns zero rows, Ns_Db1Row returns NULL. If the SQL statement returns zero rows or a database error has occurred, Ns_Db1Row returns NULL. Detailed error messages may have accumulated in an internal buffer in the Ns_DbHandle. Examples Ns_Set *row; Ns_DbHandle *handle; if ((handle = Ns_DbPoolGetHandle("aPoolName")) != NULL) { row = Ns_Db1Row(handle, "select aName from aTable"); if (row != NULL) { char *value; value = Ns_SetGet(row, "aName"); /* use `value' here */ Ns_SetFree(row); } } [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbBindRow Overview Return an Ns_Set structure of column names to be returned by the previously-executed SQL command Syntax Ns_Set *Ns_DbBindRow ( Ns_DbHandle *handle ); Description The Ns_DbBindRow function returns an Ns_Set structure whose key names are the column names of rows to be returned by the SQL command previously-executed by Ns_DbExec. If the SQL command does not return rows (i.e., the Ns_DbExec function did not return NS_ROWS), NS_ERROR is returned. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbBouncePool Overview Mark all database handles stale Syntax int Ns_DbBouncePool( char *poolname ); Description All database handles for the specified database pool are marked stale. When any database handle currently open is put back into the pool, its connection to the database will be reset. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbCancel Overview Cancel an active SQL select statement Syntax int Ns_DbCancel( Ns_DbHandle *handle ); Description The Ns_DbCancel function is similar to the Ns_DbFlush function, but instead of allowing the select statement to complete and send all selected rows, Ns_DbCancel sends a cancels message to the database. This can result in faster interruption of a long-running query. Ns_DbCancel returns NS_OK on success and NS_ERROR on error. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbDML Overview Execute an SQL DML statement Syntax int Ns_DbDML( Ns_DbHandle *handle, char *sql ); Description The Ns_DbDML function executes SQL that should be a data manipulation language statement such as an insert or update, or data definition language such as a create table. If the statement was executed successfully, Ns_DbDML returns NS_OK. If the statement results in rows being returned or a other database error, Ns_DbDML returns NS_ERROR. Detailed error messages may have accumulated in an internal buffer in the Ns_DbHandle. Examples Ns_DbHandle *handle; int status; if ((handle = Ns_DbPoolGetHandle("aPoolName")) != NULL) { status = Ns_DbDML(handle, "insert into aTable (colName1,colName2) values (1,2)"); if (status != NS_OK) { /* handle error condition */ } } [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbDriverDbType Overview Get database type Syntax char* Ns_DbDriverDbType ( Ns_DbHandle* handle ); Description Return the string name of the database type (e.g., "sybase"). [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbDriverName Overview Get driver for database Syntax char *Ns_DbDriverName( Ns_DbHandle *handle ); Description The Ns_DbDriverName function returns the name of the database driver associated with handle. The storage for the string returned is owned by the database driver and must not be freed or modified in any way. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbExec Overview Execute an SQL command Syntax int Ns_DbExec ( Ns_DbHandle *handle, char *sql ); Description The Ns_DbExec function executes the specified SQL command on the specified database connection. Ns_DbExec returns one of the following status codes: NS_ERROR if the SQL command fails NS_DML if the SQL command is DML (Data Manipulation Language) or DDL (Data Definition Language) NS_ROWS if the SQL command will return rows (such as a SELECT command) This function allows you to write a true ad hoc query tool and process SQL statements without knowing ahead of time if they return rows or are DDL or DML statements. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbFlush Overview Flush any waiting rows Syntax int Ns_DbFlush( Ns_DbHandle *handle ); Description The Ns_DbFlush function fetches and dumps any waiting rows after an Ns_DbSelect. This function is useful when you have already fetched all the rows you intend to process. Ns_DbFlush returns NS_OK after successfully flushing the database or NS_ERROR on error. Ns_DbFlush is called automatically when Ns_DbHandle's are returned to their pools with the Ns_DbPutHandle function to make sure the handle is ready the next time it is used. Some database drivers will also cancel any active transactions when Ns_DbFlush is called. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbGetRow Overview Fetch the next waiting row after an Ns_DbSelect Syntax int Ns_DbGetRow( Ns_DbHandle *handle, Ns_Set *row ); Description The Ns_DbGetRow function fetches the next row waiting to be retrieved after an Ns_DbSelect. The row Ns_Set must be the result of a previous Ns_DbSelect. Ns_DbGetRow frees any existing values of the set and sets the values to the next row fetched from the database. Possible return values are: NS_OK A row has been fetched and more rows may be waiting. NS_END_DATA No row has been fetched and there are no more rows waiting. NS_ERROR A database error occurred, or the function has already returned NS_END_DATA but has been called again anyway. You cannot call Ns_DbDML, Ns_Db1Row, or Ns_Db0or1Row with the same database handle while fetching rows from the database in an Ns_DbGetRow loop. Doing so flushes any waiting rows and a subsequent call to Ns_DbGetRow will fail. You can do so if you use separate database handles. Examples Ns_DbHandle *handle; Ns_Set *row; int status; handle = Ns_DbPoolGetHandle("mypool"); row = Ns_DbSelect(handle, "select * from mytable"); if (row == NULL) { /*... handle select error ...*/ } while ((status = Ns_DbGetRow(handle, row)) == NS_OK) { /*... process the row fetched from the database ...*/ } if (status != NS_END_DATA) { /*... handle get row error ...*/ } [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbInterpretSqlFile Overview Parse DML statements and send to database Syntax int Ns_DbInterpretSqlFile ( Ns_DbHandle* handle, char* filename ); Description Parse DML statements from an SQL file and send them to the database for execution. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbPoolAllowable Overview Determine if pool is available Syntax int Ns_DbPoolAllowable( char *hServer, char *poolname ); Description The Ns_DbPoolAllowable function returns NS_TRUE if the specified pool poolname is available on the server hServer. It returns NS_FALSE if the pool does not exist or if the server is not allowed to use this pool. See the "ns/server/server-name/module/nscgi" section in the AOLserver Administrator's Guide for information on setting allowable pools for a server. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbPoolDefault Overview Get default pool Syntax char* Ns_DbPoolDefault ( char* server ); Description Return the string name of default pool or NULL if no default is defined. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbPoolDescription Overview Get pool description Syntax char *Ns_DbPoolDescription( char *poolname ); Description The Ns_DbPoolDescription function returns the description associated with the specified pool in the AOLserver configuration file. The storage for the string returned is located in the configuration data memory. You must not deallocate or modify this string in any way. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbPoolGetHandle Overview Get database handle from pool Syntax Ns_DbHandle *Ns_DbPoolGetHandle( char *poolname ); Description The Ns_DbPoolGetHandle function gets a database handle from the pool specified by poolname. It returns NULL on error. Details relating to error conditions are written to the server log. You must request all the database handles you will need for a specific pool with one call to Ns_DbPoolGetHandle (if you need only one handle) or Ns_DbPoolGetMultipleHandles (if you need more than one handle). Examples Ns_DbHandle *handle; if ((handle = Ns_DbPoolGetHandle("aPoolName")) != NULL) { Ns_Set *row; row = Ns_DbSelect(handle, "select * from aTable"); ... } [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbPoolGetMultipleHandles Overview Get multiple database handles from pool Syntax int Ns_DbPoolGetMultipleHandles( Ns_DbHandle **handles, char *poolname, int nhandles ); Description The Ns_DbPoolGetMultipleHandles function gets a database handle from the pool specified by poolname and returns an array of handles (handles). If all of the specified number of handles (nhandles) are not available, the function waits until they are. It returns NS_OK if all requested handles are returned or NS_ERROR on an error condition. You must request all the database handles you will need for a specific pool with one call to Ns_DbPoolGetHandle (if you need only one handle) or Ns_DbPoolGetMultipleHandles (if you need more than one handle). You must release all your database handles explicitly (with Ns_DbPoolPutHandle) before acquiring more. Examples #define NUM_HANDLES 5 Ns_DbHandle **handles; handles = Ns_Malloc(NUM_HANDLES * sizeof (Ns_DbHandle *)); if (Ns_DbPoolGetMultipleHandles(handles, "aPoolName", NUM_HANDLES) != NS_OK) { Ns_Set *row; row = Ns_DbSelect(handles[0], "select * from aTable"); ... } else { /* handle error condition */ } [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbPoolList Overview Get a list of available pools for a server Syntax char *Ns_DbPoolList( char *hServer ); Description The Ns_DbPoolList function returns a list of pools available on the specified server. Upon completion, the returned pointer points to a list of pools in the following format: "pool1\0pool2\0pool3\0\0" Examples char *pools; pools = Ns_DbPoolList("serverName"); while (*pools != '\0') { printf("%s\n", pools); pools += strlen(pools) + 1; } [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbPoolPutHandle Overview Release a database handle for a pool Syntax void Ns_DbPoolPutHandle( Ns_DbHandle *handle ); Description The Ns_DbPoolPutHandle function releases the database handle handle into the pool it was derived from. If the handle was not originally obtained from a pool, an error message is written to the log. Examples Ns_DbHandle *handle; if ((handle = Ns_DbPoolGetHandle("aPoolName")) != NULL) { Ns_Set *row; row = Ns_DbSelect(handle, "select * from aTable"); ... Ns_DbPoolPutHandle(handle); /* done with handle */ } [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbPoolTimedGetHandle Overview Get database handle from pool with timeout Syntax Ns_DbHandle *Ns_DbPoolTimedGetHandle( char *poolname, int timeout ); Description The Ns_DbPoolTimedGetHandle function gets a database handle from the pool specified by poolname. If a timeout is not specified or timeout is zero, it will wait indefinitely (perhaps forever) for the handle to become available. If timeout is greater than zero, it will either return with the handle within that time period, or return "" if the time period was exceeded. If timeout is less than zero, it will not block. It returns NULL on error or if the attempt times out. Details relating to error conditions are written to the server log. You must request all the database handles you will need for a specific pool with one call to Ns_DbPoolTimedGetHandle (if you need only one handle) or Ns_DbPoolGetTimedMultipleHandles (if you need more than one handle). You must release all your database handles explicitly (with Ns_DbPoolPutHandle) before acquiring more. See Also Ns_DbPoolGetHandle [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbPoolTimedGetMultipleHandles Overview Get multiple database handles from pool with timeout Syntax int Ns_DbPoolTimedGetMultipleHandles( Ns_DbHandle **handles, char *poolname, int nhandles, int timeout ); Description The Ns_DbPoolTimedGetMultipleHandles function gets multiple database handles from the pool specified by poolname and returns an array of handles (handles). If all of the specified number of handles (nhandles) are not available, the function waits until they are, depending on timeout. If a timeout is not specified or timeout is zero, it will wait indefinitely (perhaps forever) for the handles to become available. If timeout is greater than zero, it will either return with the handles within that time period, or return "" if the time period was exceeded. If timeout is less than zero, it will not block. It returns NS_OK if all requested handles are returned, NS_TIMEOUT if the attempt timed out, or NS_ERROR on an error condition. You must request all the database handles you will need for a specific pool with one call to Ns_DbPoolTimedGetHandle (if you need only one handle) or Ns_DbPoolTimedGetMultipleHandles (if you need more than one handle). You must release all your database handles explicitly (with Ns_DbPoolPutHandle) before acquiring more. See Also Ns_DbPoolGetMultipleHandles [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbQuoteValue Overview Adds extra single quote to single quotes in string Syntax void Ns_DbQuoteValue( Ns_DString *pds, char *string ); Description The Ns_DbQuoteValue function places an additional single quote (') in front of all single quotes in the string. The result is then copied to pds. This function is typically used to pre-process a string used in an SQL statement. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbRegisterDriver Overview Register database driver with the server Syntax int Ns_DbRegisterDriver( char *hDriver, Ns_DbProc *procs ); Description The Ns_DbRegisterDriver function registers a database driver with the server. The procs argument specifies the functions that implement the driver. For a complete example of a database driver for the Postgres95 DBMS, see the directory example/C/nspg under the AOLserver installation directory. Ns_DbRegisterDriver returns a status of NS_OK or NS_ERROR. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbSelect Overview Send a row-generating query to the database Syntax Ns_Set *Ns_DbSelect( Ns_DbHandle *handle, char *sql ); Description The Ns_DbSelect function executes the given SQL statement. It returns an Ns_Set where the field key names are the column names that were returned by the select statement on success. The field values are NULL until the first call to Ns_DbGetRow where they are replaced with the values of the first row fetched from the database. The set is statically allocated; do not free it with Ns_SetFree when your query is complete. On error, Ns_DbSelect returns NULL. Detailed error message may have accumulated in an internal buffer in the Ns_DbHandle. Examples Ns_DbHandle *handle; if ((handle = Ns_DbPoolGetHandle("aPoolName")) != NULL) { Ns_Set *row; row = Ns_DbSelect(handle, "select * from aTable"); if (row == NULL) { /*... handle select error ...*/ } while ((status = Ns_DbGetRow(handle, row)) == NS_OK) { /*... process the row fetched from the database ...*/ } if (status != NS_END_DATA) { /*... handle get row error ...*/ } Ns_DbPoolPutHandle(handle); /* done with handle */ } [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbSetException Overview Set last error message for database Syntax void Ns_DbSetException( Ns_DbHandle *handle, char *code, char *msg ); Description The Ns_DbSetException function sets the last error message for the database referenced by handle. The code argument cannot be larger than 5 characters. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbSpExec Overview Run a stored procedure Syntax int Ns_DbSpExec( Ns_DbHandle *handle ); Description Run a stored procedure begun with Ns_DbSpStart. Returns NS_OK on success, NS_ERROR on failure. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbSpGetParams Overview Get output parameters from a stored procedure Syntax Ns_Set * Ns_DbSpGetParams( Ns_DbHandle *handle ); Description Get output parameters after running a stored procedure with Ns_DbSpExec. The returned set is allocated by this function and should be freed by the caller. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbSpReturnCode Overview Get return code from a stored procedure Syntax int Ns_DbSpReturnCode( Ns_DbHandle *handle, char *returnCode, int bufsize ); Description Get the return code from a stored procedure after running Ns_DbSpExec. Returns NS_OK on success, NS_ERROR on failure. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbSpSetParam Overview Set input parameter for stored procedure Syntax int Ns_DbSpSetParam( Ns_DbHandle *handle, char *paramname, char *paramtype, char *inout, char *value ); Description In preparing to run stored procedure, this function sets a parameter to pass to that stored procedure. You must have executed Ns_DbSpStart first. The paramname is the name of the parameter, such as "@foo"; paramtype is the data type, such as "int" or "varchar". The inout argument is either "in" or "out", depending on what kind of parameter it is. The value argument is the value to pass to the stored proc, such as "123" (it's always a string). Returns NS_OK on success, NS_ERROR on failure. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DbSpStart Overview Start execution of a stored procedure Syntax int Ns_DbSpStart( Ns_DbHandle *handle, char *procname ); Description Start execution of a stored procedure. This must be run before any other Ns_DbSp* call. Returns NS_OK on success, NS_ERROR on failure. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DecodeUrl Overview Decode URL query data Syntax char *Ns_DecodeUrl( Ns_DString *pds, char *data ); Description The Ns_DecodeUrl function decodes data that were encoded as URL query data. The decoded data are appended to the given Ns_DString. This function can be used to decode arguments that were passed as URL query data following a `?'. The return value is the value of pds->string, i.e., the address of the character array. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DestroyCriticalSection Overview Free a critical section's resources Syntax int Ns_DestroyCriticalSection( Ns_CriticalSection * section ); Description Free the resources associated with the critical section. Ns_CsDestroy is the preferred function for freeing a critical section's resources. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DestroyEvent Overview Free an event's resources Syntax int Ns_DestroyEvent( Ns_Event * event ); Description Free the resources associated with the event object. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DestroyMutex Overview Free a mutual exclusion lock's resources Syntax int Ns_DestroyMutex( Ns_Mutex * mutex ); Description Free the mutex's associated resources. Ns_MutexDestroy is the preferred function for freeing a mutex's resources. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DestroyRWLock Overview Destroy a read/write lock Syntax int Ns_DestroyRWLock( Ns_RWLock *lock ); Description Ns_DestroyRWLock frees the read/write lock's associated resources. For general information about read/write locks and an example showing the use of the read/write lock functions, see the Ns_InitializeRWLock function. Ns_RWLockDestroy is the preferred function for destroying a read/write lock. See Also Ns_InitializeRWLock Ns_ReadLockRWLock Ns_ReadUnlockRWLock Ns_WriteLockRWLock Ns_WriteUnlockRWLock [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DestroySemaphore Overview Free a semaphore's resources Syntax int Ns_DestroySemaphore( Ns_Semaphore * sema ); Description Free the resources associated with the semaphore. Ns_SemaDestroy is the preferred function for freeing a semaphore's resources. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DiffTime Overview Get difference between two times Syntax void Ns_DiffTime ( Ns_Time* t1, Ns_Time* t2, Ns_Time* result ); Description Determine the difference in seconds between two Ns_Time structures. The result is put into result. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DriverEnableKeepalive Overview Enable HTTP keepalive on driver Syntax void Ns_DriverEnableKeepalive ( Ns_Driver driver ); Description This function is used by socket drivers; it enables HTTP keepalive on the specified driver. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DStringAppend Overview Append a string to an Ns_DString Syntax char *Ns_DStringAppend( Ns_DString *dsPtr, char *string ); Description The Ns_DStringAppend macro appends the specified string plus a terminating null character to the end of the Ns_DString. The string may overflow from static space to the heap as a result of calling this function. It returns the string associated with the current Ns_DString. Examples Ns_DString ds; Ns_DStringInit(&ds); Ns_DStringAppend(&ds, "foo"); /* do something with the dstring */ printf("%s\n", ds.string); Ns_DStringFree(&ds); /* finished with dstring */ The resulting Ns_DString, ds, would contain "foo\0" and have a length of 3. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DStringAppendArg Overview Append argument to an Ns_DString Syntax char *Ns_DStringAppendArg( Ns_DString *dsPtr, char *arg ); Description Append the specified argument plus a terminating null character to the end of the Ns_DString. It is useful for making strings like: "foo\0bar\0baz\0". It returns the string associated with the current Ns_DString. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DStringExport Overview Export the string of an Ns_DString Syntax char *Ns_DStringExport( Ns_DString *src ); Description The Ns_DStringExport function returns the current Ns_DString string and leaves the Ns_DString in the initialized state. The string returned needs to be freed eventually with Ns_Free. Examples Ns_DString ds; char *stringdest; Ns_DStringInit(&ds); Ns_DStringAppend(&ds, "foo"); stringdest = Ns_DStringExport(&ds); /* do something with `stringdest' */ Ns_Free(stringdest); [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DStringFree Overview Free any allocated memory used by an Ns_DString Syntax void Ns_DStringFree( Ns_DString *dsPtr ); Description The Ns_DStringFree function frees any memory associated with an Ns_DString. Examples Ns_DString ds; Ns_DStringInit(&ds); Ns_DStringAppend(&ds, "foo"); /* do something with the dstring */ printf ("%s\n", ds.string); Ns_DStringFree(&ds); /* finished with dstring */ [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DStringInit Overview Initialize an Ns_DString Syntax void Ns_DStringInit( Ns_DString *dsPtr ); Description Before using an Ns_DString, you must initialize it with Ns_DStringInit. Storage for a Ns_DString is often on the stack in the calling function. The example below shows a typical usage. Examples int MyFunctions(int a, int b) { Ns_DString ds; Ns_DStringInit(&ds); /* ds is now initialized and ready to pass to another function */ ... } [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DStringLength Overview Return the current length of an Ns_DString Syntax int Ns_DStringLength( Ns_DString *dsPtr ); Description The Ns_DStringLength macro returns the current length of the Ns_DString. Examples Ns_DString ds; Ns_DStringInit(&ds); Ns_DStringAppend(&ds, "
"); printf("len=%d\n", Ns_DStringLength(&ds)); Ns_DStringFree(&ds); /* finished with dstring */ [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DStringNAppend Overview Append n-characters of a string to an Ns_DString Syntax char *Ns_DStringNAppend( Ns_DString *dsPtr, char *string, int length ); Description The Ns_DStringNAppend function appends a string up to the specified number of characters, plus a terminating null character.( Unlike the Tcl_DStringAppend function, which only works with string data, the AOLserver Ns_DStringNAppend function can append binary data.) The string may overflow from static space to the heap as a result of calling this function. It returns the string associated with the current Ns_DString. Examples The resulting Ns_DString in this example, ds, would contain "foo\0" and have a length of 3: Ns_DString ds; Ns_DStringInit(&ds); Ns_DStringNAppend(&ds, "fooasdf", 3); printf("%s\n", ds.string); Ns_DStringFree(&ds); /* finished with dstring */ If you need a null-terminated list of null-terminated strings, such as "foo\0bar\0\0", you would add one to the length of the appended strings to get the extra terminating null character. For example: Ns_DString ds; Ns_DStringInit(&ds); Ns_DStringNAppend(&ds, "foo", 4); Ns_DStringNAppend(&ds, "bar", 4); [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DStringPrintf Overview Append a formatted string to an Ns_DString Syntax char *Ns_DStringPrintf( Ns_DString *dsPtr, char *fmt, ... ); Description The Ns_DStringPrintf function appends a string that has been created by calling the sprintf function with the given format and optional arguments. This function currently uses a fixed length buffer of 1024 characters to sprintf() the data before appending to the Ns_DString. Examples Ns_DString ds; Ns_DStringInit(&ds); Ns_DStringPrintf(&ds, "/path%d", getpid()); /* do something with dstring */ printf ("%s\n", ds.string); Ns_DStringFree(&ds); /* finished with dstring */ [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DStringTrunc Overview Truncate an Ns_DString Syntax void Ns_DStringTrunc( Ns_DString *dsPtr, int length ); Description The Ns_DStringTrunc function truncates an Ns_DString to the given length. Unlike Ns_DStringFree, which truncates the Ns_DString to length 0 and frees any memory that may have been allocated on the heap, Ns_DStringTrunc allows you to truncate the string to any length. It maintains any memory allocated on the heap. This function is useful in a loop where the Ns_DString is likely to overflow the static space each time through. Using Ns_DStringTrunc instead of Ns_DStringFree will avoid having the Ns_DString call malloc to obtain the addition space in each iteration. You will need to call Ns_DStringFree eventually to free any space that may have been allocated for the Ns_DString. Examples Ns_DString ds; int i; Ns_DStringInit(&ds); for (i=0; i < 50; i++) { Ns_DStringPrintf(&ds, "%s%d", "aBigString", i); /* do something with the dstring constructed above*/ Ns_DStringTrunc(&ds, 0); } Ns_DStringFree(&ds); /* finished with dstring */ [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DStringValue Overview Return the current value of an Ns_DString Syntax char *Ns_DStringValue( Ns_DString *dsPtr ); Description The Ns_DStringValue macro returns a pointer to the current value of an Ns_DString. This may be a pointer to the Ns_DString's static space or to a string allocated on the heap if the static space has overflowed. It is not safe to use the value returned by this macro after an intervening call to Ns_DStringAppend because the Ns_DString string could overflow to or move within the heap. Examples Ns_DString ds; Ns_DStringInit(&ds); Ns_DStringAppend(&ds, "foo"); /* do something with the dstring */ printf ("%s\n", Ns_DStringValue(&ds)); Ns_DStringFree(&ds); /* finished with dstring */ [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DStringVarAppend Overview Append a variable number of strings to an Ns_DString Syntax char *Ns_DStringVarAppend( Ns_DString *dsPtr, ... ); Description The Ns_DStringVarAppend function appends a variable number of strings to an Ns_DString. The list must end with NULL. Examples Ns_DString ds; Ns_DStringInit(&ds); Ns_DStringVarAppend(&ds, "foo", "bar", NULL); /* do something with the dstring */ printf ("%s\n", ds.string); Ns_DStringFree(&ds); /* finished with dstring */ [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_DupHigh Overview Move file descriptors Syntax Ns_DupHigh( int *fd ); Description Ns_DupHigh moves file descriptors above 256 on platforms where the file descriptor in the stdio FILE structure is an unsigned char. By calling Ns_DupHigh on file descriptors that you know will not be buffered, you can leave as many low file descriptors available for stdio as possible. Ns_DupHigh is not supported on platforms where this is not an issue. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_EncodeUrl Overview Encode URL query data Syntax char *Ns_EncodeUrl( Ns_DString *pds, char *data ); Description The Ns_EncodeUrl function encodes the data as URL query data and appends the encoded data to the given Ns_DString. All characters except the alphanumerics are encoded as specified in RFC1738, Uniform Resource Locators. This function can be used to append arguments to a URL as query data following a `?'. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_Encrypt Overview Encrypt key Syntax char *Ns_Encrypt( char *key, char *salt, char buf[] ); Description The Ns_Encrypt function encrypts the specified key, perturbed by salt. The result is returned in buf, which should be at least NS_ENCRYPT_BUFSIZE bytes in size. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_EnterCriticalSection Overview Enter a critical section Syntax int Ns_EnterCriticalSection( Ns_CriticalSection * section ); Description Enter the specified critical section. If the critical section is use by another thread, the current will block until it is no longer so. Note that critical sections are recursive and must be exited the same number of times as they were entered. Ns_CsEnter is the preferred function for entering a critical section. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ExecArgblk Overview Execute file with argument string Syntax int Ns_ExecArgblk ( char* sExec, char* sDir, int fdIn, int fdOut, char* argBlk, Ns_Set* env ); Description Change current directory to sDir if it is not NULL and executes the file sExec. All input will come from fdIn if it's greater than 0; otherwise stdin will be used. All output will go to fdOut if it's greater than 0; otherwise stdout will be used. The argBlk is a string of null-separated arguments, terminated with two nulls, like this: "foo\0bar\0\0". The env is an Ns_Set containing environment variables to pass the program. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ExecArgv Overview Execute file with argument array Syntax int Ns_ExecArgv ( char* sExec, char* sDir, int fdIn, int fdOut, char** argv, Ns_Set* env ); Description Change current directory to sDir if it is not NULL and executes the file sExec. All input will come from fdIn if it's greater than 0; otherwise stdin will be used. All output will go to fdOut if it's greater than 0; otherwise stdout will be used. The argv is a null-terminated array of argument strings, like this: { "foo", "bar", NULL }. The env is an Ns_Set containing environment variables to pass the program. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ExecProc Overview Execute file with argument array Syntax int Ns_ExecProc ( char* sExec, char** argv ); Description Execute the file sExec. All input will come from stdin. All output will go to stdout. The argv is a null-terminated array of argument strings, like this: { "foo", "bar", NULL }. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ExecProcess Overview Execute file with argument string Syntax int Ns_ExecProcess ( char* sExec, char* sDir, int fdIn, int fdOut, char* argBlk, Ns_Set* env ); Description Change current directory to sDir if it is not NULL and executes the file sExec. All input will come from fdIn if it's greater than 0; otherwise stdin will be used. All output will go to fdOut if it's greater than 0; otherwise stdout will be used. The argBlk is a string of null-separated arguments, terminated with two nulls, like this: "foo\0bar\0\0". The env is an Ns_Set containing environment variables to pass the program. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ExitThread Overview Free a thread or mark as exited Syntax void Ns_ExitThread ( int retcode ); Description Cleanup the thread's tls and memory pool and either free the thread if it's detached or mark the thread as exited and allow it to be joined. Ns_ThreadExit is the preferred function for freeing a thread. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_Fatal Overview Log a fatal error and shutdown Syntax void Ns_Fatal( char *fmt, ... ); Description This function calls Ns_Log with the Fatal severity and then shuts down the server. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_FetchPage Overview Copy data from URL to dynamic string Syntax int Ns_FetchPage( Ns_DString *pds, char *url, char *hServer ); Description The Ns_FetchPage function copies data from url to the Ns_DString pointed to by pds. The URL must be relative and must correspond to a file served by this server. Ns_FetchPage returns a status of NS_OK or NS_ERROR. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_FetchURL Overview Fetch a remote URL. Syntax int Ns_FetchURL( Ns_DString *pds, char *URL, Ns_Set *headers ); Description The Ns_FetchURL function connects the AOLserver to another HTTP Web server and requests the specified URL. The URL must be fully qualified. The content is appended to the given Ns_DString. If the headers is not NULL, the HTTP headers returned in the response from the remote server are appended to the set. Ns_FetchUrl does not currently handle redirects or requests for any protocol except HTTP. Use Ns_FetchPage to get pages on the local server. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_Fork Overview Perform a fork Syntax int Ns_Fork (void); Description Performs a fork(), or on Solaris, fork1(). [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_Free Overview Free a block of allocated memory Syntax void *Ns_Free( void *buf ); Description The Ns_Free function frees any memory allocated by the Ns_Malloc, Ns_Calloc, or Ns_Realloc functions. This function replaces the system free function. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_FreeRequest Overview Free memory used by an Ns_Request Syntax void Ns_FreeRequest( Ns_Request *request ); Description The Ns_FreeRequest function frees the members of the Ns_Request and then frees the Ns_Request structure itself. The request is no longer valid and must not be used after a call to Ns_FreeRequest. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_GetConnInterp Overview Get the Tcl interpreter for the connection Syntax EXTERN Tcl_Interp *Ns_GetConnInterp( Ns_Conn *conn ); Description This function, given the conn, returns the interpreter already assigned to the conn if one exists. If no interpreter is assigned, it allocates a new interpreter and assigns it to the conn. By using this function, you can be certain that the same interpreter (and its global state) are used by the registered request function and the filters. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_GetDriver Overview Get socket driver Syntax Ns_Driver Ns_GetDriver ( char* hServer, char* hDriver ); Description Find the socket driver of the current server and the specified driver name. (The hserver argument is ignored; it is only there for backwards compatibility.) [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_GetDriverContext Overview Get socket driver context Syntax void* Ns_GetDriverContext ( Ns_Driver drv ); Description Return a socket driver's context pointer, which is set when the driver is registered with Ns_RegisterDriver. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_GetDriverLabel Overview Get socket driver label Syntax char* Ns_GetDriverLabel ( Ns_Driver driver ); Description Get the name of the socket driver as it appears in the configuration file. For example, the following configuration file entries would result in this function returning "mysocket": ns_section ns/server/server1/modules ns_param mysocket nsssl [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_GetDriverName Overview Get socket driver name Syntax char* Ns_GetDriverName ( Ns_Driver driver ); Description Get the name (for eample, `nsssl' or `nssock') of a socket driver. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc.