vortex
Class dbChannel

java.lang.Object
  vortex.dbChannel

public class dbChannel
extends java.lang.Object

This is the main VORTEXjava class. Each dbChannel object corresponds to a RDBMS connection.

Field Summary

int	dbID Unique RDBMS identifier.
boolean	null_string
int	sqlCode Last RDBMS error code
java.lang.String	sqlMsg Last RDBMS error message
java.lang.String	version Version string for included Trifox components

Constructor Summary

dbChannel(int maxLogicalCursors, int maxDbCursors, int maxColumns, int fetchBufferSize)
Allocate and initialize a dbChannel.

Method Summary

void	cancel() Cancel an outstanding request.
void	close(dbCursor cursor, boolean hard) Close a dbCursor.
boolean	Command(dbCursor cursor, int command, java.lang.String sql) Send VORTEXchannel command.
void	commit(boolean startUpdateTrans) Commit a transaction.
void	connect(java.lang.String hostName, int port, java.lang.String hostProgram, java.lang.String dbConnectString, java.lang.String envVariables) Connect to a remote RDBMS.
void	connect(java.lang.String hostName, int port, java.lang.String hostProgram, java.lang.String dbConnectString, java.lang.String envVariables, java.util.Properties info) Connect to a remote RDBMS.
void	descparms(dbCursor cursor) Describe the bind parameters
void	execute(dbCursor cursor) Execute a non-SELECT dbCursor.
void	executeIO(dbCursor cursor) Execute a stored procedure dbCursor.
void	executePX(dbCursor cursorPX, int fetDbcur) Execute a non-SELECT position exec dbCursor.
void	fetch(dbCursor cursor) Open and fetch from a SELECT dbCursor.
static java.io.File	findVortexPropFile()
dbBlob	getBlob(dbCursor cursor, int blobColumn, int maxNumBytes) Get (receive) BLOB/CLOB data from the RDBMS.
byte[]	getByte(dbCursor cursor) Get the next column as a byte array.
java.util.Date	getDate(dbCursor cursor) Get the next column as a Date.
dbNumber	getNumber(dbCursor cursor) Get the next column as a dbNumber.
int	getRowsAffected() Get the number of rows affected by the last execute() call.
void	getSkip(dbCursor cursor, int numColsToSkip, boolean stopOnColZero) Skip (pass over) columns.
java.lang.String	getString(dbCursor cursor) Get the next column as a string.
int	IPC(dbCursor cursor, java.lang.String sql) Send VORTEXchannel IPC.
boolean	isClosed() Check if connection is closed.
java.lang.String	mask(java.lang.String buf, int key) Mask the given string.
void	proxy(java.lang.String socksHost, java.lang.String socksPort) Set the SOCKS proxy.
void	putBlob(dbCursor cursor, int blobColumn, dbBlob blob) Put (send) BLOB/CLOB data to the RDBMS.
void	release() Release a connected RDBMS.
void	rollback(boolean startUpdateTrans) Rollback a transaction.
void	sql(dbCursor cursor, java.lang.String sqlStatement, int numDimensions, int numParameters) Associate a SQL statement to a dbCursor.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

version

public final java.lang.String version

Version string for included Trifox components

See Also:

Constant Field Values

null_string

public boolean null_string

dbID

public int dbID

Unique RDBMS identifier.

Each underlying RDBMS has a unique ID associated with it. This can be used for those cases when the application might want to generate RDBMS specific SQL syntax. The IDs are as follows:

• 0 - Oracle
• 1 - Rdb (Formerly DEC now Oracle)
• 2 - Sybase
• 4 - GENESIS (Trifox' flat file SQL processor)
• 5 - Informix
• 7 - DB2 (IBM)
• 8 - Ingres (CA)
• 9 - Adabas C (Software AG)
• 10 - Adabas D (Software AG)
• 11 - ODBC
• 12 - SQL Server (Microsoft)
• 16 - ODBX (B2 Systems)
• 17 - TRIMpl (Trifox)

sqlCode

public int sqlCode

Last RDBMS error code

sqlMsg

public java.lang.String sqlMsg

Last RDBMS error message

Constructor Detail

dbChannel

public dbChannel(int maxLogicalCursors,
                 int maxDbCursors,
                 int maxColumns,
                 int fetchBufferSize)

Allocate and initialize a dbChannel. This corresponds to the VTXINIT call in VORTEXcli.

Parameters

maxLogicalCursors

Maximum number of logical cursors to allocate for the connection. For best performance you should allocate one for each SQL statement.

maxDbCursor

Number of actual RDBMS cursors to allocate. The mapping of a logical cursor to a RDBMS cursor is done automatically. In general RDBMS cursor are fairly expensive to allocate (RDBMS side) and should therefore be much less than the number of logical cursors.

maxColumns

Maximum number of output columns that any given SELECT statement can have.

fetchBufferSize

Size of fetch buffer to allocate. When fetching data from the RDBMS the number of records to pre-fetch will depend on the record size. The actual fetch buffer is per dbCursor and is not allocated until the fetch() is invoked.

Examples

Allocate a connection with an 8Kb fetch buffer.

dbChannel db = new dbChannel(256,64,128,8192);

Method Detail

findVortexPropFile

public static java.io.File findVortexPropFile()

proxy

public void proxy(java.lang.String socksHost,
                  java.lang.String socksPort)

Set the SOCKS proxy.

Parameters

socksHost

SOCKS proxy host.

socksPort

SOCKS proxy port.

Example

Set the SOCKS proxy to port 1080 on firewall.

db.proxy("firewall","1080");

mask

public java.lang.String mask(java.lang.String buf,
                             int key)

Mask the given string.

Parameters

buffer

String to mask.

key

Key value to use.

connect

public void connect(java.lang.String hostName,
                    int port,
                    java.lang.String hostProgram,
                    java.lang.String dbConnectString,
                    java.lang.String envVariables,
                    java.util.Properties info)
             throws dbException

Connect to a remote RDBMS.

Parameters

hostName

Host to connect to. Can be in either the symbolic name format or the dot notation. If the VORTEXserver (vtxnetd) requires authentication then a userid and password must be appended to hostName: hostName(uid/pwd)

port

Port number that VORTEXserver (vtxnetd) is listening on.

hostProgram

Executable to service the connection. On server platforms that support DLLs this is the name of the DLL.

dbConnectString

Connect string passed to actual RDBMS.

envVariables

Optional environment variables to be set on the server.

info

Additional properties.

Throws:

dbException

connect

public void connect(java.lang.String hostName,
                    int port,
                    java.lang.String hostProgram,
                    java.lang.String dbConnectString,
                    java.lang.String envVariables)
             throws dbException

Connect to a remote RDBMS.

Parameters

hostName

Host to connect to. Can be in either the symbolic name format or the dot notation. If the VORTEXserver (vtxnetd) requires authentication then a userid and password must be appended to hostName: hostName(uid/pwd)

port

Port number that VORTEXserver (vtxnetd) is listening on.

hostProgram

Executable to service the connection. On server platforms that support DLLs this is the name of the DLL.

dbConnectString

Connect string passed to actual RDBMS.

envVariables

Optional environment variables to be set on the server.

Examples

Connect to an Oracle database on a UNIX machine.

db.connect("orahost",1958,"/usr/local/bin/vtxhost.ora",
                          "scott/tiger",
                          "ORACLE_HOME=/usr/local/oracle,ORACLE_SID=A");

Connect to a SQL Server on a NT machine.

db.connect("sqlnt",1958,"vtx12","sa/sa/master2/SQLNT","");

Connect to a DB2 database on MVS with authentication.

db.connect("sys1(foobar/dung)",1958,"7","/","");

Throws:

dbException

release

public void release()
             throws dbException

Release a connected RDBMS.

Before the actual RDBMS release request is sent a rollback() will be performed.

Throws:

dbException

commit

public void commit(boolean startUpdateTrans)
            throws dbException

Commit a transaction.

Parameters

startUpdateTrans

If true then a begin transaction will be performed immediately following the commit. This is all done on the server side therefore further minimizing the network traffic.

Throws:

dbException

rollback

public void rollback(boolean startUpdateTrans)
              throws dbException

Rollback a transaction.

Parameters

startUpdateTrans

If true then a begin transaction will be performed immediately following the rollback. This is all done on the server side therefore further minimizing the network traffic.

Throws:

dbException

sql

public void sql(dbCursor cursor,
                java.lang.String sqlStatement,
                int numDimensions,
                int numParameters)
         throws dbException

Associate a SQL statement to a dbCursor.

This method does not call the RDBMS. It simply caches the SQL statement and other info. The SQL statement will be sent to the RDBMS on either a fetch() or execute() call.

Parameters

cursor

dbCursor object.

sqlStatement

The SQL statement.

numDimension

If the SQL statement contains parameter markers (? or :n) then this specifies how many 'sets' of parameters there are. For a SELECT statement with parameters this must be 1. For INSERT/UPDATE/DELETE statements this indicate how many records to process. If the SQL statement does not contain any parameters the value must be set to 0.

numParameters

If numDimension is not 0 then this indicates the number of parameters in each 'set' of parameters.

Examples

Prepare a SELECT statment with no parameters.

db.sql(c1,"select * from staff",0,0);

Prepare a bulk INSERT statement with 7 parameters in batches of 50.

db.sql(c2,"insert into staff values (:1,:2,:3,:4,:5,:6,:7)",50,7);

Throws:

dbException

executePX

public void executePX(dbCursor cursorPX,
                      int fetDbcur)
               throws dbException

Execute a non-SELECT position exec dbCursor.

This method is typically called from VORTEXjdbc. VORTEXjava programs can simply call execute(). All the parameters specified in the sql method must be bound using dbCursor.setParam().

Throws:

dbException

execute

public void execute(dbCursor cursor)
             throws dbException

Execute a non-SELECT dbCursor.

All the parameters specified in the sql method must be bound using dbCursor.setParam(). The SQL statement will only be sent to the RDBMS the first time. On subsequent calls only the parameters (if any) are sent.

Throws:

dbException

executeIO

public void executeIO(dbCursor cursor)
               throws dbException

Execute a stored procedure dbCursor.

All the input and ouput parameters specified in the stored precedure must be bound using dbCursor.setParam(). The stored procedure statement will only be sent to the RDBMS the first time. On subsequent calls only the parameters (if any) are sent.

Throws:

dbException

putBlob

public void putBlob(dbCursor cursor,
                    int blobColumn,
                    dbBlob blob)
             throws dbException

Put (send) BLOB/CLOB data to the RDBMS.

Parameters

cursor

dbCursor object.

blobColumn

Index (zero based) of blob column.

blob

The blob data.

Throws:

dbException

getBlob

public dbBlob getBlob(dbCursor cursor,
                      int blobColumn,
                      int maxNumBytes)
               throws dbException

Get (receive) BLOB/CLOB data from the RDBMS.

There are two ways to fetch blobs. The first (and recommended) method is to fetch the length and then the blob data. Call getString() to get the length and then getblob() to fetch the blob. The second method is to keep fetching the blob until a zero length blob is returned. When a zero length blob is returned, you must call getSkip(1) to move to the next column; otherwise the subsequent data columns will be incorrect.

Parameters

cursor

dbCursor object.

blobColumn

Index (zero based) of blob column.

maxNumBytes

Maximum number of bytes to retrieve.

Throws:

dbException

fetch

public void fetch(dbCursor cursor)
           throws dbException

Open and fetch from a SELECT dbCursor.

All the parameters specified in the sql method must be bound using dbCursor.setParam(). The SQL statement will only be sent to the RDBMS the first time. On subsequent calls only the parameters (if any) are sent.

Data is automatically retrieved into a fetch buffer (using the fetch buffer size specified when the dbChannel was created). The number of rows per fetch varies depending upon the total length of a row.

The column data must be retrieved sequentially using one of the getXxxxx() methods.

This method should only be called once.

Throws:

dbException

close

public void close(dbCursor cursor,
                  boolean hard)
           throws dbException

Close a dbCursor. Note that this is not the same as discarding a dbCursor. When a dbCursor is discarded a 'hard' close() is performed.

Throws:

dbException

cancel

public void cancel()
            throws dbException

Cancel an outstanding request. This would typically be called after a user inrerrupt.

Throws:

dbException

isClosed

public boolean isClosed()
                 throws dbException

Check if connection is closed.

Throws:

dbException

getRowsAffected

public int getRowsAffected()

Get the number of rows affected by the last execute() call. This value is valid only for INSERT, UPDATE, and DELETE statements.

getString

public java.lang.String getString(dbCursor cursor)
                           throws dbException

Get the next column as a string. Numeric and Datetime data will automatically be converted to a string representation.

Throws:

dbException

getNumber

public dbNumber getNumber(dbCursor cursor)
                   throws dbException

Get the next column as a dbNumber. Once retrieved in this format the various numeric conversions supplied by dbNumber can be applied.

Throws:

dbException

getByte

public byte[] getByte(dbCursor cursor)
               throws dbException,
                      java.io.IOException

Get the next column as a byte array.

Throws:

dbException

java.io.IOException

getDate

public java.util.Date getDate(dbCursor cursor)
                       throws dbException

Get the next column as a Date. This is the standard java.util.Date class.

Throws:

dbException

getSkip

public void getSkip(dbCursor cursor,
                    int numColsToSkip,
                    boolean stopOnColZero)
             throws dbException

Skip (pass over) columns. A large numColsToSkip with stopOnColZero set to true will advance to the next row.

Parameters

cursor

dbCursor object.

numColsToSkip

Number of columns to skip over.

stopOnColZero

Never skip past column zero of the next row.

Throws:

dbException

Command

public boolean Command(dbCursor cursor,
                       int command,
                       java.lang.String sql)
                throws dbException

Send VORTEXchannel command.

Throws:

dbException

IPC

public int IPC(dbCursor cursor,
               java.lang.String sql)
        throws dbException

Send VORTEXchannel IPC.

Throws:

dbException

descparms

public void descparms(dbCursor cursor)
               throws dbException

Describe the bind parameters

Throws:

dbException