DbPool

Represents a pool of connections to a particular database configuration.

Server-side object

Implemented in
Netscape Server 3.0

To connect to a database, you first create a pool of database connections and then access individual connections as needed. For more information on the general methodology for using DbPool objects, see Writing Server-Side JavaScript Applications.

Created by

The DbPool constructor.

Properties

prototype

Represents the prototype for this class. You can use the prototype to add properties or methods to all instances of a class. For information on prototypes, see Function.prototype.

Property of
DbPool

Implemented in
LiveWire 1.0

Methods

DbPool

Creates a pool of database Connection objects and optionally connects the objects to a particular configuration of database and user.

Method of
DbPool

Implemented in
Netscape Server 3.0

Syntax

new DbPool();

new DbPool (dbtype, serverName, username, password, databaseName);

new DbPool (dbtype, serverName, username, password, databaseName, maxConnections);

new DbPool (dbtype, serverName, username, password, databaseName, maxConnections, commitflag);

Parameters

dbtype
Database type. One of ORACLE, SYBASE, INFORMIX, DB2, or ODBC.

serverName
Name of the database server to which to connect. The server name typically is established when the database is installed and is different for different database types:
DB2: Local database alias. On both NT and UNIX, this is set up by the client or the DB2 Command Line Processor.
Informix: Informix server. On NT, this is specified with the setnet32 utility; on UNIX, in the sqlhosts file.
Oracle: Service. On both NT and UNIX, this specified in the tnsnames.ora file. On NT, you can use the SQL*Net easy configuration to specify it. When your Oracle database server is local, specify the empty string for this argument.
ODBC: Data source name. On NT, this is specified in the ODBC Administrator; on UNIX, in the .odbc.ini file. If you are using the Web Server as a user the file .odbc.ini must be in your home directory; if as a system, it must be in the root directory.
Sybase: Server name (the DSQUERY parameter). On NT, this is specified with the sqledit utility; on UNIX, with the sybinit utility.
If in doubt, see your database or system administrator. For ODBC, this is the name of the ODBC service as specified in Control Panel.

userName
Name of the user to connect to the database. Some relational database management systems (RDBMS) require that this be the same as your operating system login name; others maintain their own collections of valid user names. See your system administrator if you are in doubt.

password
User's password. If the database does not require a password, use an empty string ("").

databaseName
Name of the database to connect to for the given serverName. If your database server supports the notion of multiple databases on a single server, supply the name of the database to use. If it does not, use an empty string (""). For Oracle, ODBC, and DB2, you must always use an empty string.
For Oracle, specify this information in the tnsnames.ora file.
For ODBC, if you want to connect to a particular database, specify the database name specified in the datasource definition.
For DB2, there is no concept of a database name; the database name is always the server name (as specified with serverName).

maxConnections
(Optional) Number of connections to be created and cached in the pool. The runtime engine attempts to create as many connections as specified with this parameter. If successful, it stores those connections for later use. If you do not supply this parameter, its value is 1.
Remember that your database client license probably specifies a maximum number of connections. Do not set this parameter to a number higher than your license allows. For Sybase, you can have at most 100 connections.
If your database client library is not multithreaded, it can only support one connection at a time. In this case, your application performs as though you specified 1 for this parameter. For a current list of which database client libraries are multithreaded, see the Enterprise Server 3.0 Release Notes.

commitFlag
(Optional) A Boolean value indicating whether to commit a pending transaction when the connection is released or the object is finalized.
(If the transaction is on a single page, the object is finalized at the end of the page. If the transaction spans multiple pages, the object is finalized when the connection returns to the pool.)
If this parameter is false, a pending transaction is rolled back. If this parameter is true, a pending transaction if committed. For DbPool, the default value is false; for database, the default value is true. If you specify this parameter, you must also specify the maxConnections parameter.

Description

The first version of this constructor takes no parameters. It instantiates and allocates memory for a DbPool object. This version of the constructor creates and caches one connection. When this connection goes out of scope, pending transactions are rolled back.

The second version of this constructor instantiates a DbPool object and then calls the connect method to establish a database connection. This version of the constructor also creates and caches one connection. When this connection goes out of scope, pending transactions are rolled back.

The third version of this constructor instantiates a DbPool object and then calls the connect method to establish a database connection. In addition, it attempts to create as many connections as specified by the maxConnections parameter. If successful, it stores those connections for later use. If the runtime engine does not obtain the requested connections, it returns an error. When this connection goes out of scope, pending transactions are rolled back.

The fourth version of this constructor does everything the third version does. In addition, the commitflag parameter indicates what to do with pending transactions when the connection goes out of scope. If this parameter is false (the default), a pending transaction is rolled back. If this parameter is true, a pending transaction if committed.

To detect errors, you can use the majorErrorCode method.

If possible, your application should call this constructor and make the database connection on its initial page. Doing so prevents conflicts from multiple client requests trying to manipulate the status of the connections at once.

connect

Connects the pool to a particular configuration of database and user.

Method of
DbPool

Implemented in
Netscape Server 3.0

Syntax

connect (dbtype, serverName, username, password, databaseName)

connect (dbtype, serverName, username, password, databaseName, maxConnections)

connect (dbtype, serverName, username, password, databaseName, maxConnections, commitflag)

Parameters

dbtype
Database type; one of ORACLE, SYBASE, INFORMIX, DB2, or ODBC.

serverName
Name of the database server to which to connect. The server name typically is established when the database is installed and is different for different database types:
DB2: Local database alias. On both NT and UNIX, this is set up by the client or the DB2 Command Line Processor.
Informix: Informix server. On NT, this is specified with the setnet32 utility; on UNIX, in the sqlhosts file.
Oracle: Service. On both NT and UNIX, this specified in the tnsnames.ora file. On NT, you can use the SQL*Net easy configuration to specify it. When your Oracle database server is local, specify the empty string for this argument.
ODBC: Data source name. On NT, this is specified in the ODBC Administrator; on UNIX, in the .odbc.ini file. If you are using the Web Server as a user the file .odbc.ini must be in your home directory; if as a system, it must be in the root directory.
Sybase: Server name (the DSQUERY parameter). On NT, this is specified with the sqledit utility; on UNIX, with the sybinit utility.
If in doubt, see your database or system administrator. For ODBC, this is the name of the ODBC service as specified in Control Panel.

userName
Name of the user to connect to the database. Some relational database management systems (RDBMS) require that this be the same as your operating system login name; others maintain their own collections of valid user names. See your system administrator if you are in doubt.

password
User's password. If the database does not require a password, use an empty string ("").

databaseName
Name of the database to connect to for the given serverName. If your database server supports the notion of multiple databases on a single server, supply the name of the database to use. If it does not, use an empty string (""). For Oracle, ODBC, and DB2, you must always use an empty string.
For Oracle, specify this information in the tnsnames.ora file.
For ODBC, if you want to connect to a particular database, specify the database name specified in the datasource definition.
For DB2, there is no concept of a database name; the database name is always the server name (as specified with serverName).

maxConnections
(Optional) Number of connections to be created and cached in the pool. The runtime engine attempts to create as many connections as specified with this parameter. If successful, it stores those connections for later use. If you do not supply this parameter, its value is 1.
Remember that your database client license probably specifies a maximum number of connections. Do not set this parameter to a number higher than your license allows. For Sybase, you can have at most 100 connections.
If your database client library is not multithreaded, it can only support one connection at a time. In this case, your application performs as though you specified 1 for this parameter. For a current list of which database client libraries are multithreaded, see the Enterprise Server 3.0 Release Notes.

commitFlag
(Optional) A Boolean value indicating whether to commit a pending transaction when the connection goes out of scope. If this parameter is false, a pending transaction is rolled back. If this parameter is true, a pending transaction if committed. For DbPool, the default value is false; for database, the default value is true. If you specify this parameter, you must also specify the maxConnections parameter.

Returns

0 if the call was successful; otherwise, a nonzero status code based on any error message passed by the database. If the method returns a nonzero status code, use the associated majorErrorCode and majorErrorMessage methods to interpret the cause of the error.

Description

When you call this method, the runtime engine first closes and releases any currently open connections. It then reconnects the pool with the new configuration. You should be sure that all connections have been released before calling this method.

The first version of this method creates and caches one connection. When this connection goes out of scope, pending transactions are rolled back.

The second version of this method attempts to create as many connections as specified by the maxConnections parameter. If successful, it stores those connections for later use. If the runtime engine does not obtain the requested connections, it returns an error. When this connection goes out of scope, pending transactions are rolled back.

The third version of this method does everything the second version does. In addition, the commitflag parameter indicates what to do with pending transactions when this connection goes out of scope. If this parameter is false (the default), a pending transaction is rolled back. If this parameter is true, a pending transaction if committed.

Example

The following statement creates four connections to an Informix database named mydb on a server named myserver, with user name SYSTEM and password MANAGER. Pending transactions are rolled back at the end of a client request:

pool.connect("INFORMIX", "myserver", "SYSTEM", "MANAGER", "mydb", 4)

connected

Tests whether the database pool and all of its connections are connected to a database.

Method of
DbPool

Implemented in
Netscape Server 3.0

Syntax

connected()

Parameters

None.

Returns

True if the pool (and hence a particular connection in the pool) is currently connected to a database; otherwise, false.

Description

The connected method indicates whether this object is currently connected to a database.

If this method returns false for a Connection object, you cannot use any other methods of that object. You must reconnect to the database, using the DbPool object, and then get a new Connection object. Similarly, if this method returns false for the database object, you must reconnect before using other methods of that object.

Example

Example 1: The following code fragment checks to see if the connection is currently open. If it's not, it reconnects the pool and reassigns a new value to the myconn variable.

if (!myconn.connected()) {
   mypool.connect ("INFORMIX", "myserver", "SYSTEM", "MANAGER", "mydb", 4);
   myconn = mypool.connection;
}

Example 2: The following example uses an if condition to determine if an application is connected to a database server. If the application is connected, the isConnectedRoutine function runs; if the application is not connected, the isNotConnected routine runs.

if(database.connected()) {
   isConnectedRoutine() }
else {
   isNotConnectedRoutine() }

connection

Retrieves an available connection from the pool.

Method of
DbPool

Implemented in
Netscape Server 3.0

Syntax

connection (name, timeout)

Parameters

name
An arbitrary name for the connection. Primarily used for debugging.

timeout
The number of seconds to wait for an available connection before returning. The default is to wait indefinitely. If you specify this parameter, you must also specify the name parameter.

Returns

A new Connection object.

disconnect

Disconnects all connections in the pool from the database.

Method of
DbPool

Implemented in
Netscape Server 3.0

Syntax

disconnect()

Parameters

None.

Returns

Description

For the DbPool object, before calling the disconnect method, you must first call the release method for all connections in this database pool. Otherwise, the connection is still considered in use by the system, so the disconnect waits until all connections are released.

After disconnecting from a database, the only methods of this object you can use are connect and connected.

Examples

The following example uses an if condition to determine if an application is connected to a database server. If the application is connected, the application calls the disconnect method; if the application is not connected, the isNotConnected routine runs.

if(database.connected()) {
   database.disconnect() }
else {
   isNotConnectedRoutine() }

majorErrorCode

Major error code returned by the database server or ODBC.

Method of
DbPool

Implemented in
Netscape Server 3.0

Syntax

majorErrorCode()

Parameters

None.

Returns

The result returned by this method depends on the database server being used:

Informix: the Informix error code.

Oracle: the code as reported by Oracle Call-level Interface (OCI).

Sybase: the DB-Library error number or the SQL server message number.

Description

SQL statements can fail for a variety of reasons, including referential integrity constraints, lack of user privileges, record or table locking in a multiuser database, and so on. When an action fails, the database server returns an error message indicating the reason for failure. The LiveWire Database Service provides two ways of getting error information: from the status code returned by various methods or from special properties containing error messages and codes.

Status codes are integers between 0 and 27, with 0 indicating a successful execution of the statement and other numbers indicating an error, as shown in

Status Code	Explanation	Status Code	Explanation
0	No error	14	Null reference parameter
1	Out of memory	15	Connection object not found
2	Object never initialized	16	Required information is missing
3	Type conversion error	17	Object cannot support multiple readers
4	Database not registered	18	Object cannot support deletions
5	Error reported by server	19	Object cannot support insertions
6	Message from server	20	Object cannot support updates
7	Error from vendor's library	21	Object cannot support updates
8	Lost connection	22	Object cannot support indices
9	End of fetch	23	Object cannot be dropped
10	Invalid use of object	24	Incorrect connection supplied
11	Column does not exist	25	Object cannot support privileges
12	Invalid positioning within object (bounds error)	26	Object cannot support cursors
13	Unsupported feature	27	Unable to open

Examples

This example updates the rentals table within a transaction. The updateRow method assigns a database status code to the statusCode variable to indicate whether the method is successful.

If updateRow succeeds, the value of statusCode is 0, and the transaction is committed. If updateRow returns a statusCode value of either five or seven, the values of majorErrorCode, majorErrorMessage, minorErrorCode, and minorErrorMessage are displayed. If statusCode is set to any other value, the errorRoutine function is called.

database.beginTransaction()
statusCode = cursor.updateRow("rentals")

if (statusCode == 0) {
   database.commitTransaction()
   }

if (statusCode == 5 || statusCode == 7) {
   write("The operation failed to complete.<BR>"
   write("Contact your system administrator with the following:<P>"
   write("The value of statusCode is " + statusCode + "<BR>")
   write("The value of majorErrorCode is " +
      database.majorErrorCode() + "<BR>")
   write("The value of majorErrorMessage is " +
      database.majorErrorMessage() + "<BR>")
   write("The value of minorErrorCode is " +
      database.minorErrorCode() + "<BR>")
   write("The value of minorErrorMessage is " +
      database.minorErrorMessage() + "<BR>")
   database.rollbackTransaction()
   }

else {
   errorRoutine()
   }

majorErrorMessage

Major error message returned by database server or ODBC. For server errors, this typically corresponds to the server's SQLCODE.

Method of
DbPool

Implemented in
Netscape Server 3.0

Syntax

majorErrorMessage()

Parameters

None.

Returns

A string describing that depends on the database server:

Informix: "Vendor Library Error: string," where string is the error text from Informix.

Oracle: "Server Error: string," where string is the translation of the return code supplied by Oracle.

Sybase: "Vendor Library Error: string," where string is the error text from DB-Library or "Server Error string," where string is text from the SQL server, unless the severity and message number are both 0, in which case it returns just the message text.

Description

SQL statements can fail for a variety of reasons, including referential integrity constraints, lack of user privileges, record or table locking in a multiuser database, and so on. When an action fails, the database server returns an error message indicating the reason for failure. The LiveWire Database Service provides two ways of getting error information: from the status code returned by connection and DbPool methods or from special connection or DbPool properties containing error messages and codes.

Examples

See DbPool.majorErrorCode.

minorErrorCode

Secondary error code returned by database vendor library.

Method of
DbPool

Implemented in
Netscape Server 3.0

Syntax

minorErrorCode()

Parameters

None.

Returns

The result returned by this method depends on the database server:

Informix: the ISAM error code, or 0 if there is no ISAM error.

Oracle: the operating system error code as reported by OCI.

Sybase: the severity level, as reported by DB-Library or the severity level, as reported by the SQL server.

minorErrorMessage

Secondary message returned by database vendor library.

Method of
DbPool

Implemented in
Netscape Server 3.0

Syntax

minorErrorMessage()

Parameters

None.

Returns

The string returned by this method depends on the database server:

Informix: "ISAM Error: string," where string is the text of the ISAM error code from Informix, or an empty string if there is no ISAM error.

Oracle: the Oracle server name.

Sybase: the operating system error text, as reported by DB-Library or the SQL server name.

storedProcArgs

Creates a prototype for a DB2, ODBC, or Sybase stored procedure.

Method of
DbPool

Implemented in
Netscape Server 3.0

Syntax

storedProcArgs (procName, type1, ..., typeN)

Parameters

procName
The name of the procedure.

type1, ..., typeN
Each typeI is one of: "IN", "OUT", or "INOUT" Specifies the type of each parameter: input ("IN"), output ("OUT"), or both input and output ("INOUT").

Returns

Nothing.

Description

This method is only for Sybase stored procedures.

This method provides the procedure name and the parameters for that stored procedure. Sybase stored procedures can accept parameters that are only for input ("IN"), only for output ("OUT"), or for both input and output ("INOUT").

You must create one prototype for each Sybase stored procedure you use in your application. Additional prototypes for the same stored procedure are ignored.

You can specify an INOUT parameter either as an INOUT or as an OUT parameter. If you use an INOUT parameter of a stored procedure as an OUT parameter, the LiveWire Database Service implicitly passes a NULL value for that parameter.

Examples

Assume the inoutdemo stored procedure takes one input parameter and one input/output parameter, as follows:

create procedure inoutdemo ( @inparam int, @inoutparam int output)
as
if ( @inoutparam == null)
@inoutparam = @inparam + 1
else
@inoutparam = @inoutparam + 1

Assume execute the following code and then call outParameters(0), the result will be 101:

database.storedProcArgs("inoutdemo", "IN", "INOUT")
spobj= database.storedProc("inoutdemo", 6, 100);
answer = spobj.outParameters(0);

The value of answer is 101. On the other hand, assume you execute this code:

database.storedProcArgs("inoutdemo", "IN", "OUT")
spobj = database.storedProc("inoutdemo", 6, 100);
answer = spobj.outParameters(0);

In this case, the value of answer is 7.

toString

Returns a string representing the specified object.

Method of
DbPool

Implemented in
Netscape Server 3.0

Syntax

toString()

Parameters

None.

Description

Every object has a toString method that is automatically called when it is to be represented as a text value or when an object is referred to in a string concatenation.

You can use toString within your own code to convert an object into a string, and you can create your own function to be called in place of the default toString method.

This method returns a string of the following format:

db "name" "userName" "dbtype" "serverName"

where

name
The name of the database.

userName
The name of the user connected to the database.

dbType
One of ORACLE, SYBASE, INFORMIX, DB2, or ODBC.

serverName
The name of the database server.

The method displays an empty string for any of attributes whose value is unknown.

For information on defining your own toString method, see the Object.toString method.

[Contents] [Previous] [Next] [Index]

Last Updated: 10/31/97 16:35:15

`DbPool`	Creates a pool of database Connection objects and optionally connects the objects to a particular configuration of database and user.
`connect`	Connects the pool to a particular configuration of database and user.
`connected`	Tests whether the database pool and all of its connections are connected to a database.
`connection`	Retrieves an available connection from the pool.
`disconnect`	Disconnects all connections in the pool from the database.
`majorErrorCode`	Major error code returned by the database server or ODBC.
`majorErrorMessage`	Major error message returned by database server or ODBC. For server errors, this typically corresponds to the server's SQLCODE.
`minorErrorCode`	Secondary error code returned by database vendor library.
`minorErrorMessage`	Secondary message returned by database vendor library.
`storedProcArgs`	Creates a prototype for a Sybase stored procedure.
`toString`	Returns a string representing the specified object.

dbtype	Database type. One of `ORACLE`, `SYBASE`, `INFORMIX`, `DB2`, or `ODBC`.
serverName	Name of the database server to which to connect. The server name typically is established when the database is installed and is different for different database types: DB2: Local database alias. On both NT and UNIX, this is set up by the client or the DB2 Command Line Processor. Informix: Informix server. On NT, this is specified with the setnet32 utility; on UNIX, in the sqlhosts file. Oracle: Service. On both NT and UNIX, this specified in the tnsnames.ora file. On NT, you can use the SQL*Net easy configuration to specify it. When your Oracle database server is local, specify the empty string for this argument. ODBC: Data source name. On NT, this is specified in the ODBC Administrator; on UNIX, in the .odbc.ini file. If you are using the Web Server as a user the file .odbc.ini must be in your home directory; if as a system, it must be in the root directory. Sybase: Server name (the DSQUERY parameter). On NT, this is specified with the sqledit utility; on UNIX, with the sybinit utility. If in doubt, see your database or system administrator. For ODBC, this is the name of the ODBC service as specified in Control Panel.
userName	Name of the user to connect to the database. Some relational database management systems (RDBMS) require that this be the same as your operating system login name; others maintain their own collections of valid user names. See your system administrator if you are in doubt.
password	User's password. If the database does not require a password, use an empty string ("").
databaseName	Name of the database to connect to for the given `serverName`. If your database server supports the notion of multiple databases on a single server, supply the name of the database to use. If it does not, use an empty string (""). For Oracle, ODBC, and DB2, you must always use an empty string. For Oracle, specify this information in the tnsnames.ora file. For ODBC, if you want to connect to a particular database, specify the database name specified in the datasource definition. For DB2, there is no concept of a database name; the database name is always the server name (as specified with `serverName`).
maxConnections	(Optional) Number of connections to be created and cached in the pool. The runtime engine attempts to create as many connections as specified with this parameter. If successful, it stores those connections for later use. If you do not supply this parameter, its value is 1. Remember that your database client license probably specifies a maximum number of connections. Do not set this parameter to a number higher than your license allows. For Sybase, you can have at most 100 connections. If your database client library is not multithreaded, it can only support one connection at a time. In this case, your application performs as though you specified 1 for this parameter. For a current list of which database client libraries are multithreaded, see the Enterprise Server 3.0 Release Notes.
commitFlag	(Optional) A Boolean value indicating whether to commit a pending transaction when the connection is released or the object is finalized. (If the transaction is on a single page, the object is finalized at the end of the page. If the transaction spans multiple pages, the object is finalized when the connection returns to the pool.) If this parameter is false, a pending transaction is rolled back. If this parameter is true, a pending transaction if committed. For DbPool, the default value is false; for database, the default value is true. If you specify this parameter, you must also specify the `maxConnections` parameter.

dbtype	Database type; one of ORACLE, SYBASE, INFORMIX, DB2, or ODBC.
serverName	Name of the database server to which to connect. The server name typically is established when the database is installed and is different for different database types: DB2: Local database alias. On both NT and UNIX, this is set up by the client or the DB2 Command Line Processor. Informix: Informix server. On NT, this is specified with the setnet32 utility; on UNIX, in the sqlhosts file. Oracle: Service. On both NT and UNIX, this specified in the `tnsnames.ora` file. On NT, you can use the SQL*Net easy configuration to specify it. When your Oracle database server is local, specify the empty string for this argument. ODBC: Data source name. On NT, this is specified in the ODBC Administrator; on UNIX, in the .odbc.ini file. If you are using the Web Server as a user the file .odbc.ini must be in your home directory; if as a system, it must be in the root directory. Sybase: Server name (the DSQUERY parameter). On NT, this is specified with the sqledit utility; on UNIX, with the sybinit utility. If in doubt, see your database or system administrator. For ODBC, this is the name of the ODBC service as specified in Control Panel.
userName	Name of the user to connect to the database. Some relational database management systems (RDBMS) require that this be the same as your operating system login name; others maintain their own collections of valid user names. See your system administrator if you are in doubt.
password	User's password. If the database does not require a password, use an empty string ("").
databaseName	Name of the database to connect to for the given `serverName`. If your database server supports the notion of multiple databases on a single server, supply the name of the database to use. If it does not, use an empty string (""). For Oracle, ODBC, and DB2, you must always use an empty string. For Oracle, specify this information in the tnsnames.ora file. For ODBC, if you want to connect to a particular database, specify the database name specified in the datasource definition. For DB2, there is no concept of a database name; the database name is always the server name (as specified with `serverName`).
maxConnections	(Optional) Number of connections to be created and cached in the pool. The runtime engine attempts to create as many connections as specified with this parameter. If successful, it stores those connections for later use. If you do not supply this parameter, its value is 1. Remember that your database client license probably specifies a maximum number of connections. Do not set this parameter to a number higher than your license allows. For Sybase, you can have at most 100 connections. If your database client library is not multithreaded, it can only support one connection at a time. In this case, your application performs as though you specified 1 for this parameter. For a current list of which database client libraries are multithreaded, see the Enterprise Server 3.0 Release Notes.
commitFlag	(Optional) A Boolean value indicating whether to commit a pending transaction when the connection goes out of scope. If this parameter is false, a pending transaction is rolled back. If this parameter is true, a pending transaction if committed. For DbPool, the default value is false; for database, the default value is true. If you specify this parameter, you must also specify the `maxConnections` parameter.

name	An arbitrary name for the connection. Primarily used for debugging.
timeout	The number of seconds to wait for an available connection before returning. The default is to wait indefinitely. If you specify this parameter, you must also specify the `name` parameter.

procName	The name of the procedure.
type1, ..., typeN	Each `typeI` is one of: `"IN"`, `"OUT"`, or `"INOUT"` Specifies the type of each parameter: input (`"IN"`), output (`"OUT"`), or both input and output (`"INOUT"`).

name	The name of the database.
userName	The name of the user connected to the database.
dbType	One of `ORACLE`, `SYBASE`, `INFORMIX, DB2`, or `ODBC`.
serverName	The name of the database server.