vortex
Class dbChannel

java.lang.Object
  extended by 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:


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


Updated May 06 2016