Oracle C++ Call Interface Programmer's Guide Release 9.0.1 Part Number A89860-01 |
|
This chapter describes the OCCI classes and methods for C++.
The topics discussed include:
Table 8-1 provides a brief description of all the OCCI classes. This section is followed by detailed descriptions of each class and its methods.
Table 8-1 OCCI Classes
OCCI classes are defined in the oracle::occi
namespace. An OCCI class name within the oracle::occi
namespace can be referred to in one of three ways:
::
) for each OCCI class name.
using
declaration for each OCCI class name.
using
directive for all OCCI class name.
The scope resolution operator (::
) is used to explicitly specify the oracle::occi
namespace and the OCCI class name. To declare myConnection
, a Connection
object, using the scope resolution operator, you would use the following syntax:
oracle::occi::Connection myConnection;
The using
declaration is used when the OCCI class name can be used in a compilation unit without conflict. To declare the OCCI class name in the oracle::occi
namespace, you would use the following syntax:
using oracle::occi::Connection;
Connection
now refers to oracle::occi::Connection
, and myConnection
can be declared as:
Connection myConnection;
The using
directive is used when all OCCI class names can be used in a compilation unit without conflict. To declare all OCCI class names in the oracle::occi
namespace, you would use the following syntax:
using oracle::occi;
Then, just as with the using
declaration, the following declaration would now refer to the OCCI class Connection
:
Connection myConnection;
The Bfile
class defines the common properties of objects of type BFILE
. A BFILE is a large binary file stored in an operating system file outside of the Oracle database. A Bfile
object contains a logical pointer to a BFILE, not the BFILE itself.
Methods of the Bfile
class enable you to perform specific tasks related to Bfile
objects.
Methods of the ResultSet
and Statement classes
, such as getBfile()
and setBfile()
, enable you to access a SQL BFILE value.
To create a null Bfile object, use the syntax:
Bfile();
The only methods valid on a null Bfile
object are setNull()
, isNull(),
and operator=()
.
To create an uninitialized Bfile
object, use the syntax:
Bfile(const Connection *connectionp
);
An uninitialized Bfile
object can be initialized by:
The setName() method
. The BFILE can then be modified by inserting this BFILE into the table and then retrieving it using SELECT
... FOR UPDATE.
The write()
method will modify the BFILE; however, the modified data will be flushed to the table only when the transaction is committed. Note that an insert is not required.
Bfile
object to it.
To create a copy of an existing Bfile
object, use the syntax:
Bfile(const Bfile &srcBfile
);
This method closes a previously opened BFILE.
void close();
This method closes the stream obtained from the BFILE.
void closeStream(Stream *stream
);
The stream to be closed.
This method tests whether the BFILE exists. If the BFILE exists, then true is returned; otherwise, false is returned.
bool fileExists() const;
This method returns a string containing the directory alias associated with the BFILE
.
string getDirAlias() const;
This method returns a string containing the file name associated with the BFILE.
string getFileName() const;
This method returns a Stream
object read from the BFILE. If a stream is already open, it is disallowed to open another stream on the Bfile object
. The stream must be closed before performing any Bfile
object operations.
Stream* getStream(unsigned int offset = 1,unsigned int amount = 0);
The starting position at which to begin reading data from the BFILE. If offset
is not specified, the data is written from the beginning of the BLOB.
Valid values are:
Numbers greater than or equal to 1.
The total number of bytes to be read from the BFILE; if amount
is 0, the data will be read in a streamed mode from input offset
until the end of the BFILE.
This method tests whether the Bfile
object has been initialized. If the Bfile
object has been initialized, then true is returned; otherwise, false is returned.
bool isInitialized() const;
This method tests whether the Bfile
object is atomically null. If the Bfile
object is atomically null, then true is returned; otherwise, false is returned.
bool isNull() const;
This method tests whether the BFILE is open. The BFILE is considered to be open only if it was opened by a call on this Bfile
object. (A different Bfile
object could have opened this file as more than one open can be performed on the same file by associating the file with different Bfile
objects). If the BFILE is open, then true is returned; otherwise, false is returned.
bool isOpen() const;
This method returns the number of bytes (inclusive of the end of file marker) in the BFILE.
unsigned int length() const;
This method opens an existing BFILE for read-only access. This function is meaningful the first time it is called for a Bfile
object.
void open();
This method assigns a Bfile
object to the current Bfile
object. The source Bfile
object is assigned to this Bfile
object only when this Bfile
object gets stored in the database.
Bfile& operator=(const Bfile &srcBfile);
The Bfile object
to be assigned to the current Bfile
object.
This method compares two Bfile objects
for equality. The Bfile
objects are equal if they both refer to the same BFILE. If the Bfile
objects are null, then false is returned. If the Bfile
objects are equal, then true is returned; otherwise, false is returned.
bool operator==(const Bfile &srcBfile) const;
The Bfile object
to be compared with the current Bfile
object.
This method compares two Bfile objects
for inequality. The Bfile
objects are equal if they both refer to the same BFILE. If the Bfile
objects are not equal, then true is returned; otherwise, false is returned.
bool operator!=(const Bfile &srcBfile) const;
The Bfile object
to be compared with the current Bfile
object.
This method reads a part or all of the BFILE into the buffer specified, and returns the number of bytes read.
unsigned int read(unsigned int amt,unsigned char *buffer, unsigned int bufsize, unsigned int offset = 1) const;
The number of bytes to be read.
Valid values are:
Numbers greater than or equal to 1.
The buffer that the BFILE data is to be read into.
Valid values are:
A number greater than or equal to amt
.
The size of the buffer that the BFILE data is to be read into.
Valid values are:
A number greater than or equal to amt
.
The starting position at which to begin reading data from the BFILE. If offset
is not specified, the data is written from the beginning of the BFILE.
This method sets the directory alias and file name of the BFILE.
void setName(const string &dirAlias,const string &fileName);
The directory alias to be associated with the BFILE.
The file name to be associated with the BFILE.
This method sets the Bfile object
to atomically null.
void setNull();
The Blob
class defines the common properties of objects of type BLOB. A BLOB is a large binary object stored as a column value in a row of a database table. A Blob
object contains a logical pointer to a BLOB, not the BLOB itself.
Methods of the Blob
class enable you to perform specific tasks related to Blob
objects.
Methods of the ResultSet
and Statement
classes, such as getBlob()
and setBlob()
, enable you to access an SQL BLOB value.
To create a null Blob object
, use the syntax:
Blob();
The only methods valid on a null Blob
object are setNull
(), isNull
(), and operator=()
.
To create an uninitialized Blob object, use the syntax:
Blob(const Connection *connectionp);
An uninitialized Blob object
can be initialized by:
The setEmpty
() method. The BLOB
can then be modified by inserting this BLOB into the table and then retrieving it using SELECT
... FOR
UPDATE
. The write
() method will modify the BLOB; however, the modified data will be flushed to the table only when the transaction is committed. Note that an update is not required.
Blob
object to it.
To create a copy of a Blob
object, use the syntax:
Blob(const Blob &srcBlob);
This method appends a BLOB to the end of the current BLOB.
void append(const Blob &srcBlob);
The BLOB to be appended to the current BLOB.
This method closes a BLOB.
void close();
This method closes the Stream object obtained from the BLOB.
void closeStream(Stream *stream);
The Stream
object to be closed.
This method copies a part or all of the BFILE or BLOB into the current BLOB.
There are variants of syntax:
void copy(const Bfile &srcBfile,unsigned int numBytes, unsigned int dstOffset = 1, unsigned int srcOffset = 1);
void copy(const Blob &srcBlob,unsigned int numBytes, unsigned int dstOffset = 1, unsigned int srcOffset = 1);
The BFILE from which the data is to be copied.
The BLOB from which the data is to be copied.
The number of bytes to be copied from the source BFILE or
BLOB.
Valid values are:
Numbers greater than 0.
The starting position at which to begin writing data into the current BLOB.
Valid values are:
Numbers greater than or equal to 1.
The starting position at which to begin reading data from the source BFILE or BLOB.
Valid values are:
Numbers greater than or equal to 1.
This method returns the chunk size of the BLOB.
When creating a table that contains a BLOB, the user can specify the chunking factor, which can be a multiple of Oracle blocks. This corresponds to the chunk size used by the LOB data layer when accessing or modifying the BLOB.
unsigned int getChunkSize() const;
This method returns a Stream
object from the BLOB. If a stream is already open, it is disallowed to open another stream on Blob object
, so the user must always close the stream before performing any Blob
object operations.
Stream* getStream(unsigned int offset = 1,unsigned int amount = 0);
The starting position at which to begin reading data from the BLOB.
Valid values are:
Numbers greater than or equal to 1.
The total number of consecutive bytes to be read. If amount
is 0, the data will be read from the offset
value until the end of the BLOB.
This method tests whether the Blob
object is initialized. If the Blob
object is initialized, then true is returned; otherwise, false is returned.
bool isInitialized() const;
This method tests whether the Blob
object is atomically null. If the Blob
object is atomically null, then true is returned; otherwise, false is returned.
bool isNull() const;
This method tests whether the BLOB is open. If the BLOB is open, then true is returned; otherwise, false is returned.
bool isOpen() const;
This method returns the number of bytes in the BLOB.
unsigned int length() const;
This method opens the BLOB in read-write or read-only mode
.
void open(LobOpenMode mode = OCCI_LOB_READWRITE);
The mode the
BLOB is to be opened in.
Valid values are:
OCCI_LOB_READWRITE
OCCI_LOB_READONLY
This method assigns a BLOB to the current BLOB. The source BLOB gets copied to the destination BLOB only when the destination BLOB gets stored in the table.
Blob& operator=(const Blob &srcBlob);
The BLOB to copy data from.
This method compares two Blob objects
for equality. Two Blob objects
are equal if they both refer to the same BLOB. Two null Blob objects
are not considered equal. If the Blob
objects are equal, then true is returned; otherwise, false is returned.
bool operator==(const Blob &srcBlob) const;
The Blob
object to be compared with the current Blob
object.
This method compares two Blob objects
for inequality. Two Blob objects
are equal if they both refer to the same BLOB. Two null Blob
objects are not considered equal. If the Blob
objects are not equal, then true is returned; otherwise, false is returned.
bool operator!=(const Blob &srcBlob) const;
The Blob
object to be compared with the current Blob
object.
This method reads a part or all of the BLOB into a buffer. The actual number of bytes read is returned.
unsigned int read(unsigned int amt,unsigned char *buffer, unsigned int bufsize, unsigned int offset = 1) const;
The number of consecutive bytes to be read from the BLOB.
The buffer into which the BLOB data is to be read.
The size of the buffer.
Valid values are:
Numbers greater than or equal to amount
.
The starting position at which to begin reading data from the BLOB. If offset
is not specified, the data is written from the beginning of the BLOB.
Valid values are:
Numbers greater than or equal to 1.
This method sets the Blob
object to empty.
void setEmpty();
This method sets the Blob
object to atomically null.
void setNull();
This method truncates the BLOB to the new length specified.
void trim(unsigned int newlen);
The new length of the BLOB.
Valid values are:
Numbers less than or equal to the current length of the BLOB.
This method writes data from a buffer into a BLOB. This method implicitly opens the BLOB, copies the buffer into the BLOB, and implicitly closes the BLOB. If the BLOB is already open, use writeChunk()
instead. The actual number of bytes written is returned.
unsigned int write(unsigned int amt,unsigned char *buffer, unsigned int bufsize, unsigned int offset = 1);
The number of consecutive bytes to be written to the BLOB.
The buffer containing the data to be written to the BLOB.
The size of the buffer containing the data to be written to the
BLOB.
Valid values are:
Numbers greater than or equal to amt
.
The starting position at which to begin writing data into the BLOB. If offset
is not specified, the data is written from the beginning of the BLOB.
Valid values are:
Numbers greater than or equal to 1.
This method writes data from a buffer into a previously opened BLOB. The actual number of bytes written is returned.
unsigned int writeChunk(unsigned int amt,unsigned char *buffer, unsigned int bufsize, unsigned int offset = 1);
The number of consecutive bytes to be written to the BLOB.
The buffer containing the data to be written.
The size of the buffer
containing the data to be written.
Valid values are:
Numbers greater than or equal to amt
.
The starting position at which to begin writing data into the BLOB. If offset
is not specified, the data is written from the beginning of the BLOB.
Valid values are:
Numbers greater than or equal to 1.
Methods of the Bytes
class enable you to perform specific tasks related to Bytes
objects.
To create a Bytes
object, use the syntax:
Bytes(Environment *env = NULL);
To create a Bytes
object that contains a subarray of bytes from a character array, use the syntax:
Bytes(unsigned char *value,unsigned int count, unsigned int offset = 0, Environment *env = NULL);
To create a copy of a Bytes
object, use the syntax:
Bytes(const Bytes &e);
This method returns the byte at the specified position in the Bytes
object.
unsigned char byteAt(unsigned int index) const;
The position of the byte to be returned from the Bytes
object; the first byte of the Bytes
object is at 0.
This method copies bytes from a Bytes
object into the specified byte array.
void getBytes(unsigned char *dst,unsigned int count, unsigned int srcBegin = 0, unsigned int dstBegin = 0) const;
The destination buffer into which data from the Bytes
object is to be written.
The number of bytes to copy.
The starting position at which data is to be read from the Bytes
object; the position of the first byte in the Bytes
object is at 0.
The starting position at which data is to be written in the destination buffer; the position of the first byte in dst
is at 0.
This method tests whether the Bytes
object is atomically null. If the Bytes
object is atomically null, then true is returned; otherwise false is returned.
bool isNull() const;
This method returns the length of the Bytes
object.
unsigned int length() const;
This method sets the Bytes
object to atomically null.
void setNull();
The Clob class defines the common properties of objects of type CLOB. A CLOB is a large character object stored as a column value in a row of a database table. A Clob
object contains a logical pointer to a CLOB, not the CLOB itself.
Methods of the Clob class enable you to perform specific tasks related to Clob
objects, including methods for getting the length of a SQL CLOB, for materializing a CLOB on the client, and for extracting a part of the CLOB.
Methods in the ResultSet
and Statement
classes, such as getClob()
and setClob()
, enable you to access an SQL CLOB value.
To create a null Clob
object, use the syntax:
Clob();
The only methods valid on a null Clob
object are setNull
(), isNull
(), and operator=()
.
To create an uninitialized Clob
object, use the syntax:
Clob(const Connection *connectionp);
An uninitialized Clob
object can be initialized by:
The setEmpty
() method. The CLOB
can then be modified by inserting this CLOB into the table and retrieving it using SELECT
... FOR
UPDATE. The write
() method will modify the CLOB; however, the modified data will be flushed to the table only when the transaction is committed. Note that an insert
is not required.
Clob
object to it.
To create a copy of a Clob
object, use the syntax:
This method appends a CLOB to the end of the current CLOB.
void append(const Clob &srcClob);
The CLOB to be appended to the current CLOB.
This method closes a CLOB.
void close();
This method closes the Stream
object obtained from the CLOB.
void closeStream(Stream *stream);
The Stream
object to be closed.
This method copies a part or all of a BFILE or CLOB into the current CLOB.
There are variants of syntax:
void copy(const Bfile &srcBfile,unsigned int numBytes, unsigned int dstOffset = 1, unsigned int srcOffset = 1);void copy(const Clob &srcClob,unsigned int numBytes, unsigned int dstOffset = 1, unsigned int srcOffset = 1);
The BFILE from which the data is to be copied.
The CLOB from which the data is to be copied.
The number of characters to be copied from the source BFILE or
CLOB.
Valid values are:
Numbers greater than 0.
The starting position at which to begin writing data into the current CLOB.
Valid values are:
Numbers greater than or equal to 1.
The starting position at which to begin reading data from the source BFILE or CLOB.
Valid values are:
Numbers greater than or equal to 1.
This method returns the character set form of the CLOB.
CharSetForm getCharSetForm() const;
This method returns the character set ID of the CLOB.
CharSet getCharSetId() const;
This method returns the chunk size of the CLOB.
When creating a table that contains a CLOB, the user can specify the chunking factor, which can be a multiple of Oracle blocks. This corresponds to the chunk size used by the LOB data layer when accessing and modifying the CLOB.
unsigned int getChunkSize() const;
This method returns a Stream
object from the CLOB. If a stream is already open, it is disallowed to open another stream on Clob object
, so the user must always close the stream before performing any Clob
object operations.
Stream* getStream(unsigned int offset = 1,unsigned int amount = 0, CharSet charsetId = DefaultCharSet, CharSetForm charsetForm = OCCI_SQLCS_IMPLICIT);
The starting position at which to begin reading data from the CLOB. If offset
is not specified, the data is written from the beginning of the CLOB.
Valid values are:
Numbers greater than or equal to 1.
The total number of consecutive characters to be read. If amount
is 0, the data will be read from the offset
value until the end of the CLOB.
The character set ID of the CLOB.
The character set form of the CLOB.
This method tests whether the Clob object
is initialized. If the Clob
object is initialized, true is returned; otherwise, false is returned.
bool isInitialized() const;
This method tests whether the Clob
object is atomically null. If the Clob
object is atomically null, true is returned; otherwise, false is returned.
bool isNull() const;
This method tests whether the CLOB is open. If the CLOB is open, true is returned; otherwise, false is returned.
bool isOpen() const;
This method returns the number of characters in the CLOB.
unsigned int length() const;
This method opens the CLOB in read-write
or read-only mode.
void open(LObOpenMode mode = OCCI_LOB_READWRITE);
The mode the
CLOB is to be opened in.
Valid values are:
OCCI_LOB_READWRITE
OCCI_LOB_READONLY
This method assigns a CLOB to the current CLOB. The source CLOB gets copied to the destination CLOB only when the destination CLOB gets stored in the table.
Clob& operator=(const Clob &srcClob);
The CLOB to copy data from.
This method compares two Clob
objects for equality. Two Clob
objects are equal if they both refer to the same CLOB. Two null Clob
objects are not considered equal. If the Blob
objects are equal, then true is returned; otherwise, false is returned.
bool operator==(const Clob &srcClob) const;
The Clob object
to be compared with the current Clob
object.
This method compares two Clob objects
for inequality. Two Clob
objects are equal if they both refer to the same CLOB. Two null Clob
objects are not considered equal. If the Clob
objects are not equal, then true is returned; otherwise, false is returned.
bool operator!=(const Clob &srcClob) const;
The Clob
object to be compared with the current Clob
object.
This method reads a part or all of the CLOB into a buffer. The actual number of characters read is returned.
unsigned int read(unsigned int amt,unsigned char *buffer, unsigned int bufsize, unsigned int offset = 1, CharSet charsetId = DefaultCharSet, CharSetForm charsetForm = OCCI_SQLCS_IMPLICIT) const;
The number of consecutive characters to be read from the CLOB.
The buffer into which the CLOB data is to be read.
The size of the buffer
.
Valid values are:
Numbers greater than or equal to amt
.
The position at which to begin reading data from the CLOB. If offset
is not specified, the data is read from the beginning of the CLOB.
Valid values are:
Numbers greater than or equal to 1.
The character set ID of the CLOB.
The character set form of the CLOB.
This method sets the Clob
object to empty.
void setEmpty();
This method sets the Clob
object to atomically null.
void setNull();
This method truncates the CLOB to the new length specified.
void trim(unsigned int newlen);
The new length of the CLOB.
Valid values are:
Numbers less than or equal to the current length of the CLOB.
This method writes data from a buffer into a CLOB. This method implicitly opens the CLOB, copies the buffer into the CLOB, and implicitly closes the CLOB. If the CLOB is already open, use writeChunk()
instead. The actual number of characters written is returned.
unsigned int write(unsigned int amt,unsigned char *buffer, unsigned int bufsize, unsigned int offset = 1, CharSet charsetId = DefaultCharSet, CharSetForm charsetForm = OCCI_SQLCS_IMPLICIT);
The number of consecutive characters to be written to the CLOB.
The buffer containing the data to be written to the CLOB.
The size of the buffer containing the data
to be written to the CLOB.
Valid values are:
Numbers greater than or equal to amt
.
The position at which to begin writing data into the CLOB. If offset
is not specified, the data is written from the beginning of the CLOB.
Valid values are:
Numbers greater than or equal to 1.
The character set ID of the buffer data.
The character set form of the buffer data.
This method writes data from a buffer into a previously opened CLOB. The actual number of characters written is returned.
unsigned int writechunk(unsigned int amt,unsigned char *buffer, unsigned int bufsize, unsigned int offset = 1, CharSet charsetId = DefaultCharSet, CharSetForm charsetForm = OCCI_SQLCS_IMPLICIT);
The number of consecutive characters to be written to the CLOB.
The buffer containing the data to be written to the CLOB.
The size of the buffer containing the data to be written to the CLOB.
Valid values are:
Numbers greater than or equal to amt
.
The position at which to begin writing data into the CLOB. If offset
is not specified, the data is written from the beginning of the CLOB.
Valid values are:
Numbers greater than or equal to 1.
The character set ID of the CLOB.
The character set form of the CLOB.
The Connection class represents a connection with a specific database. Within the context of a connection, SQL statements are executed and results are returned.
To create a connection, use the syntax:
Connection();
This method changes the password of the user currently connected to the database.
void changePassword(const string &user,const string &oldPassword, const string &newPassword);
The user currently connected to the database.
The current password of the user.
The new password of the user.
This method commits all changes made since the previous commit or rollback, and releases any database locks currently held by the session.
void commit();
This method creates a Statement
object with the SQL statement specified.
Statement* createStatement(const string &sql ="");
This method flushes the object cache associated with the connection.
void flushCache();
This method returns the default client character set.
CharSet getClientCharSet() const;
This method returns the default client NCHAR character set.
CharSet getClientNCHARCharSet() const;
This method returns metadata for an object in the database.
There are variants of syntax:
MetaData getMetaData(const string &object,MetaData::ParamType prmtyp = MetaData::PTYPE_UNK) const;MetaData getMetaData(const RefAny &ref) const;
This method returns the OCI server context associated with the connection.
OCIServer* getOCIServer() const;
This method returns the OCI service context associated with the connection.
OCISvcCtx* getOCIServiceContext() const;
This method returns the OCI session context associated with the connection.
OCISession* getOCISession() const;
This method drops all changes made since the previous commit or rollback, and releases any database locks currently held by the session.
void rollback();
This method closes a Statement
object and frees all resources associated with it.
void terminateStatement(Statement *statement);
The Statement
to be closed.
The ConnectionPool class represents a pool of connections for a specific database.
To create a connection pool, use the syntax:
ConnectionPool();
This method creates a pooled connection.
Connection* createConnection(const string &userName,const string &password);
The name of the user to connect as.
The password of the user.
This method creates a proxy connection from the connection pool.
There are variants of syntax:
Connection* createProxyConnection(cont string &name,Connection::ProxyType proxyType = Connection::PROXY_DEFAULT);
Connection* createProxyConnection(const string &name,string roles[], int numRoles, Connection::ProxyType proxyType = Connection::PROXY_DEFAULT);
The user name to connect with.
The roles to activate on the database server.
The number of roles to activate on the database server.
The type of proxy authentication to perform.
Valid values are:
PROXY_DEFAULT representing a database user name.
PROXY_EXTERNAL_AUTH representing an external user name.
This method returns the number of busy connections in the connection pool.
unsigned int getBusyConnections() const;
This method returns the number of incremental connections in the connection pool.
unsigned int getIncrConnections() const;
This method returns the maximum number of connections in the connection pool.
unsigned int getMaxConnections() const;
This method returns the minimum number of connections in the connection pool.
unsigned int getMinConnections() const;
This method returns the number of open connections in the connection pool.
unsigned int getOpenConnections() const;
This method returns the name of the connection pool.
string getPoolName() const;
This method returns the time-out period of a connection in the connection pool.
unsigned int getTimeOut() const;
This method specifies that a SQLException is to be generated when all connections in the connection pool are busy and no further connections can be opened.
void setErrorOnBusy();
This method sets the minimum, maximum, and incremental number of pooled connections for the connection pool.
void setPoolSize(unsigned int minConn = 0,
unsigned int maxConn = 1,
unsigned int incrConn = 1);
The minimum number of connections for the connection pool.
The maximum number of connections for the connection pool.
The incremental number of connections for the connection pool.
This method sets the time-out period for a connection in the connection pool. OCCI will terminate any connections related to this connection pool that have been idle for longer than the time-out period specified.
void setTimeOut(unsigned int connTimeOut = 0);
The time-out period in number of seconds.
This method terminates the pooled connection or proxy connection.
void terminateConnection(Connection *connection);
The pooled connection or proxy connection to terminate.
The Date class specifies the abstraction for a SQL DATE data item. The Date class also adds formatting and parsing operations to support the OCCI escape syntax for date values.
Since SQL92 DATE is a subset of Oracle Date, this class can be used to support both.
To create a null Date
object, use the syntax:
Date();
To create a copy of a Date
object, use the syntax:
Date(const Date &a);
To create a Date
object using integer parameters, where:
year |
-4712 to 9999, except 0 |
month |
1 to 12 |
day |
1 to 31 |
minutes |
0 to 59 |
seconds |
0 to 59 |
use the syntax:
Date(const Environment *envp,int year = 1, unsigned int month = 1, unsigned int day = 1, unsigned int hour = 0, unsigned int minute = 0, unsigned int seconds = 0);
Objects from the Date class can be used as standalone class objects in client side numerical computations and also used to fetch from and set to the database.
The following code example demonstrates a Date column value being retrieved from the database, a bind using a Date object, and a computation using a standalone Date object:
/* Create a connection */ Environment *env = Environment::createEnvironment(Environment::DEFAULT); Connection *conn = env->createConnection(user, passwd, db); /* Create a statement and associate a DML statement to it */ string sqlStmt = "SELECT job-id, start_date from JOB_HISTORY where end_date = :x"; Statement *stmt = conn->createStatement(sqlStmt); /* Create a Date object and bind it to the statement */ Date edate(env, 2000, 9, 3, 23, 30, 30); stmt->setDate(1, edate); ResultSet *rset = stmt->executeQuery(); /* Fetch a date from the database */ while(rset->next()) {Date sd = rset->getDate(2); Date temp = sd; /*assignment operator */ /* Methods on Date */ temp.getDate(year, month, day, hour, minute, second); temp.setMonths(2); IntervalDS inter = temp.daysBetween(sd); . . .}
This method adds a specified number of days to the Date
object and returns the new date.
Date addDays(int i) const;
The number of days to be added to the current Date
object.
This method adds a specified number of months to the Date
object and returns the new date.
Date addMonths(int i) const;
The number of months to be added to the current Date
object.
This method returns the number of days between the current Date
object and the date specified
.
IntervalDS daysBetween(const Date &d) const;
The date to be used.
This method converts a Bytes
object....
void fromBytes(const Bytes &byteStream,const Environment *envp = NULL);
Date
in external format in the form of Bytes.
This method converts a string...
void fromText(const string &datestr,const string &fmt = "", const string &nlsParam = "", const Environment *envp = NULL);
The date string to be converted.
The format string.
A string specifying the nls parameters to be used.
The environment from which the nls parameters are to be obtained.
This method returns the date in the form of the date components year, month, day, hour, minute, seconds.
void getDate(int &year,unsigned int &month, unsigned int &day, unsigned int &hour, unsigned int &min, unsigned int &sec) const;
Storage for year
Storage for month
Storage for day
Storage for hour
Storage for minute
Storage for sec
This method returns the system date.
static Date getSystemDate(const Environment *envp);
This method tests whether the Date
is null. If the Date
is null, true is returned; otherwise, false is returned.
bool isNull() const;
This method returns a date representing the last day of the current month.
Date lastDay() const;
This method returns a date representing the day after the day of the week specified.
Date nextDay(const string &dow) const;
Day Of Week.
This method assigns ...
Date& operator=(const Date &d);
A date.
This method compares the dates specified. If the dates are equal, true is returned; otherwise, false is returned.
bool operator==(const Date &a,const Date &b);
A date.
Another date.
This method compares the dates specified. If the dates are not equal then true is returned; otherwise, false is returned.
bool operator!=(const Date &a,const Date &b);
A date.
Another date.
This method compares the dates specified. If the first date is in the future relative to the second date then true is returned; otherwise, false is returned. If either date is null then false is returned. If the dates are
not the same type then false is returned.
bool operator>(const Date &a,const Date &b);
A date.
Another date.
This method compares the dates specified. If the first date is in the future relative to the second date or the dates are equal then true is returned; otherwise, false is returned. If either date is null then false is returned. If the dates are not the same type then false is returned.
bool operator>=(const Date &a,const Date &b);
A date.
Another date.
This method compares the dates specified. If the first date is in the past relative to the second date then true is returned; otherwise, false is returned. If either date is null then false is returned. If the dates are not the same type then false is returned.
bool operator<(const Date &a,const Date &b);
A date.
Another date.
This method compares the dates specified. If the first date is in the past relative to the second date or the dates are equal then true is returned; otherwise, false is returned. If either date is null then false is returned. If the dates are not the same type then false is returned.
bool operator<=(const Date &a,const Date &b);
A date.
Another date.
This method sets the date to the values specified.
void setDate(int year = 1,unsigned int month = 1, unsigned int day = 1, unsigned int hour = 0, unsigned int minute = 0, unsigned int seconds = 0);
This method set the date to atomically null.
void setNull();
This method returns the date in Bytes
representation.
Bytes toBytes() const;
This method returns a string with the value of this date formatted using fmt
and nlsParam
.
string toText(const string &fmt = "",const string &nlsParam = "") const;
The fmt string.
A string specifying the nls parameters to be used.
This method returns Date
value converted from one time zone to another
. Valid time zones are:
Date toZone(const string &zone1,const string &zone2) const;
Time zone to be converted from.
Time zone to be converted to.
The Environment class provides an OCCI environment to manage memory and other resources for OCCI objects.
The application can have multiple OCCI environments. Each environment would have its own heap and thread-safety mutexes and so forth.
To create an Environment
object, use the syntax:
Environment() enum Mode {DEFAULT = OCI_DEFAULT, OBJECT = OCI_OBJECT, SHARED = OCI_SHARED, NO_USERCALLBACKS = OCI_NO_UCB, THREADED_MUTEXED = OCI_THREADED, THREADED_UNMUTEXED = OCI_THREADED | OCI_ENV_NO_MUTEX};
Method | Summary |
Create a connection to a database. |
|
Create a connection pool. |
|
Create an environment and use the specified memory management functions. |
|
Return the current amount of memory allocated to all objects in the current environment. |
|
getMap()() |
Return the Map for the current environment. |
Return the OCI environment associated with the current environment. |
|
Close the connection and free all related resources. |
|
Close the connection pool and free all related resources. |
|
Destroy the environment. |
This method establishes a connection to the database specified.
Connection * createConnection(const string &username,const string &password, const string &connectString);
The name of the user to connect as.
The password of the user.
The database to connect to.
This method creates a connection pool based on the parameters specified.
ConnectionPool* createConnectionPool(const string &poolUserName,const string &poolPassword, const string &connectString = "", unsigned int minConn = 0, unsigned int maxConn = 1, unsigned int incrConn = 1);
This method creates an Environment
object. It is created with the specified memory management functions specified in the setMemMgrFunctions()
method. If no memory manager functions are specified, then OCCI uses its own default functions. An Environment
object must eventually be closed to free all the system resources it has acquired.
If the mode specified is THREADED_MUTEXED or THREADED_UN_MUTEXED, then all three memory management functions must be thread-safe.
static Environment * createEnvironment(Mode mode = DEFAULT,void *ctxp = 0, void *(*malocfp)(void *ctxp, size_t size) = 0, void *(*ralocfp)(void *ctxp, void *memptr, size_t newsize) = 0, void (*mfreefp)(void *ctxp, void *memptr) = 0);
Valid values are:
DEFAULT not thread safe, not in object mode
THREADED_MUTEXED thread safe, mutexed internally by OCCI
THREADED_UN-MUTEXTED thread safe, client responsible for mutexing
OBJECT uses object features
Context pointer for user-defined memory management function.
The size of the memory to be allocated by user-defined memory allocation function.
User-defined memory allocation function.
User-defined memory reallocation function.
User-defined memory free function.
This method returns the amount of memory currently allocated to all objects in this environment.
unsigned int getCurrentHeapSize() const;
This method returns a pointer to the map for this environment.
Map *getMap() const;
This method returns a pointer to the OCI environment associated with this environment.
OCIEnv *getOCIEnvironment() const;
This method closes the connection to the environment, and frees all related system resources.
void terminateConnection(Connection *connection);
This method closes the connections in the connection pool, and frees all related system resources.
void terminateConnectionPool(ConnectionPool *poolp);
This method closes the environment, and frees all related system resources.
void terminateEnvironment(Environment *env);
Environment to be closed.
Leading field precision will be determined by number of decimal digits in day input. Fraction second precision will be determined by number of fraction digits on input.
IntervalDS(const Environment *env,int day = 0, int hour = 0, int minute = 0, int second = 0, int fs = 0);
0 to 999999999
0 to 23
0 to 59
0 to 59
0 to 999999
Constructs an IntervalDS
object from the given string.The string is interpreted using the nls parameters set in the environment.
IntervalDS(const Environment *env,const string &inpstr);
Input string representing a year month interval of the form 'days hours:minutes:seconds' for example, '10 20:14:10.2'
Constructs a null IntervalDS
object. A null intervalDS
can be initialized by assignment or calling fromText
method. Methods that can be called on null intervalDS
objects are setNull
and isNull
.
IntervalDS();
Constructs an IntervalDS object as a copy of an Interval reference.
IntervalDS(const Interval &src);
The following code example demonstrates that the default constructor creates a null value, and how you can assign a non null value to a day-second interval and then perform operations on it:
Environment *env = Environment::createEnvironment(); //create a null day-second interval IntervalDS ds if(ds.isnull())cout << "\n ds is null";//assign a non null value to ds IntervalDS anotherDS(env, "10-30"); ds = anotherDS; //now all operations are valid on DS... int DAY = ds.getDay();
The following code example demonstrates how to create a null day-second interval, initialize the day-second interval by using the fromText
method, add to the day-second interval by using the += operator, multiply by using the * operator, compare 2 day-second intervals, and convert a day-second interval to a string by using the toText
method:
Environment *env = Environment::createEnvironment(); //create a null day-second interval IntervalDS ds1 //initialize a null day-second interval by using the fromText method ds1.fromText("20 10:20:30.9","",env); IntervalDS addWith(env,2,1); ds1 += addWith; //call += operator IntervalDS mulDs1=ds1 * Number(env,10); //call * operator if(ds1==mulDs1) //call == operator. . .;string strds=ds1.toText(2,4); //2 is leading field precision //4 is the fractional field precision
This method creates the interval from the string specified. The string is converted using the nls parameters, if specified, associated with the relevant environment.
If nlsParam
is specified, this will determine the nls parameters to be used for the conversion. If nlsParam
is not specified, the nls parameters are picked up from env
. If env
is null, the nls parameters are picked up from the environment associated with the instance, if any.
void fromText(const string &inpstr,const string &nlsParam = "", const Environment *env = NULL);
Input string representing a day second interval of the form 'days hours:minutes:seconds' for example, '10 20:14:10.2'
This method returns the day component of the interval.
int getDay() const;
This method returns the fractional second component of the interval.
int getFracSec() const;
This method returns the hour component of the interval.
int getHour() const;
This method returns the minute component of this interval.
int getMinute() const;
This method returns the seconds component of this interval.
int getSecond() const;
This method tests whether the interval is null. If the interval is null then true is returned; otherwise, false is returned.
bool isNull() const;
This method returns ...
const IntervalDS operator*(const IntervalDS &a,const Number &factor
);
A day second interval.
This method assigns the product of IntervalDS
and a
to IntervalDS
.
IntervalDS& operator*=(const IntervalDS &a);
A day second interval.
This method assigns the specified value to the interval.
IntervalDS& operator=(const IntervalDS &src);
This method compares the intervals specified. If the intervals are equal then true is returned; otherwise, false is returned. If either interval is null then false is returned.
bool operator==(const IntervalDS &a,const IntervalDS &b
);
An day second interval.
Another day second interval.
This method compares the intervals specified. If the intervals are not equal then true is returned; otherwise, false is returned. If either interval is null then false is returned.
bool operator!=(const IntervalDS &a,const IntervalDS &b);
An day second interval.
Another day second interval.
This method returns ... .
const IntervalDS operator/(const IntervalDS &a,const Number &factor
);
A day second interval.
This method assigns the quotient of IntervalDS
and a
to IntervalDS
.
IntervalDS& operator/=(const IntervalDS &a);
A day second interval.
This method compares the intervals specified. If the first interval is greater than the second interval then true is returned; otherwise, false is returned. If either interval is null then false is returned.
bool operator>(const IntervalDS &a,const IntervalDS &b
);
A day second interval.
Another day second interval.
This method compares the intervals specified. If the first interval is greater than or equal to the second interval then true is returned; otherwise, false is returned. If either interval is null then false is returned.
bool operator>=(const IntervalDS &a,const IntervalDS &b);
This method compares the intervals specified. If the first interval is less than the second interval then true is returned; otherwise, false is returned. If either interval is null then false is returned.
bool operator<(const IntervalDS &a,const IntervalDS &b
);
A day second interval.
Another day second interval.
This method compares the intervals specified. If the first interval is less than or equal to the second interval then true is returned; otherwise, false is returned. If either interval is null then false is returned.
bool operator<=(const IntervalDS &a,const IntervalDS &b);
A day second interval.
Another day second interval.
This method returns the difference between the intervals a
and b
.
const IntervalDS operator-(const IntervalDS &a,const IntervalDS &b
);
A day second interval.
Another day second interval.
This method assigns the difference between IntervalDS
and a
to IntervalDS
.
IntervalDS& operator-=(const IntervalDS &a);
A day second interval.
This method returns the sum of the intervals specified.
const IntervalDS operator+(const IntervalDS &a,const IntervalDS &b
);
A day second interval.
Another day second interval.
This method assigns the sum of IntervalDS
and a
to IntervalDS
.
IntervalDS& operator+=(const IntervalDS &a);
A day second interval.
This method sets the interval to the values specified.
void set(int day,int hour, int minute, int second, int fracsec);
0 to 999999999
0 to 23
0 to 59
0 to 59
0 to 999999
This method sets the interval to null.
void setNull();
This method ...
string toText(unsigned int lfprec,unsigned int fsprec, const string &nlsParam = "") const;
IntervalYM
supports the SQL92 datatype Year-Month Interval.
Leading field precision will be determined by number of decimal digits on input.
IntervalYM(const Environment *env,int year = 0, int month=0);
0 to 999999999
0 to 11
Constructs an IntervalYM
object from the given string. The string is interpreted using the nls parameters set in the environment.
IntervalYM(const Environment *env,const string &inpstr);
Input string representing a year month interval of the form `year-month'
Constructs a null IntervalYM
object. A null intervalYM can be initialized by assignment or calling fromText
method. Methods that can be called on null intervalYM
objects are setNull
and isNull
.
IntervalYM();
Constructs an IntervalYM
object from src
.
IntervalYM(const IntervalYM &src);
The following code example demonstrates that the default constructor creates a null value, and how you can assign a non null value to a year-month interval and then perform operations on it:
Environment *env = Environment::createEnvironment(); //create a null year-month interval IntervalYM ym if(ym.isnull())cout << "\n ym is null";//assign a non null value to ym IntervalYM anotherYM(env, "10-30"); ym = anotherYM; //now all operations are valid on ym... int yr = ym.getYear();
The following code example demonstrates how to get the year-month interval column from a result set, add to the year-month interval by using the += operator, multiply by using the * operator, compare 2 year-month intervals, and convert a year-month interval to a string by using the toText
method:
//SELECT WARRANT_PERIOD from PRODUCT_INFORMATION //obtain result set resultset->next(); //get interval value from resultset IntervalYM ym1 = resultset->getIntervalYM(1); IntervalYM addWith(env, 10, 1); ym1 += addWith; //call += operator IntervalYM mulYm1 = ym1 * Number(env, 10); //call * operator if(ym1<mulYm1) //comparison. . .;string strym = ym1.toText(3); //3 is the leading field precision
This method creates the interval from the string specified. The string is converted using the nls parameters, if specified, associated with the relevant environment.
initializes the interval to the values in inpstr
. The string is interpreted using the nls parameters set in the environment.
If nlsParam
is specified, this will determine the nls parameters to be used for the conversion. If nlsParam
is not specified, the nls parameters are picked up from env
. If env
is null, the nls parameters are picked up from the environment associated with the instance, if any.
void fromText(const string &inpstr,const string &nlsParam = "", const Environment *env =NULL
);
Input string representing a year month interval of the form `year-month'
This method returns the month component of the interval.
int getMonth() const;
This method returns the year component of the interval.
int getYear() const;
This method tests whether the interval is null. If the interval is null then true is returned; otherwise, false is returned.
bool isNull() const;
This method returns ...
const IntervalYM operator*(const IntervalYM &a,const Number &factor
);
A year month interval.
This method assigns the product of IntervalYM
and a
to IntervalYM
.
IntervalYM& operator*=(const IntervalYM &a);
A year month interval.
This method assigns the specified value to the interval.
const IntervalYM& operator=(const IntervalYM &src);
A year month interval.
This method compares the intervals specified. If the intervals are equal then true is returned; otherwise, false is returned. If either interval is null then false is returned.
bool operator==(const IntervalYM &a,const IntervalYM &b
);
A year month interval.
Another year month interval.
This method compares the intervals specified. If the intervals are not equal then true is returned; otherwise, false is returned. If either interval is null then false is returned.
bool operator!=(const IntervalYM &a,const IntervalYM &b);
A year month interval.
Another year month interval.
This method returns ...
const IntervalYM operator/(const IntervalYM &a,const Number &factor
);
A year month interval.
Another year month interval.
This method assigns the quotient of IntervalYM
and a
to IntervalYM
.
IntervalYM& operator/=(const IntervalYM &a);
A year month interval.
This method compares the intervals specified. If the first interval is greater than the second interval then true is returned; otherwise, false is returned. If either interval is null then false is returned.
bool operator>(const IntervalYM &a,const IntervalYM &b
);
A year month interval.
Another year month interval.
This method compares the intervals specified. If the first interval is greater than or equal to the second interval then true is returned; otherwise, false is returned. If either interval is null then false is returned.
bool operator>=(const IntervalYM &a,const IntervalYM &b);
A year month interval.
Another year month interval.
This method compares the intervals specified. If the first interval is less than the second interval then true is returned; otherwise, false is returned. If either interval is null then false is returned.
bool operator<(const IntervalYM &a,const IntervalYM &b
);
A year month interval.
Another year month interval.
This method compares the intervals specified. If the first interval is less than or equal to the second interval then true is returned; otherwise, false is returned. If either interval is null then false is returned.
bool operator<=(const IntervalYM &a,const IntervalYM &b);
A year month interval.
Another year month interval.
This method returns the difference between the intervals specified.
const IntervalYM operator-(const IntervalYM &a,const IntervalYM &b
);
A year month interval.
Another year month interval.
This method assigns the difference between IntervalYM
and a
to IntervalYM
.
IntervalYM& operator-=(const IntervalYM &a);
A year month interval.
This method returns the sum of the intervals specified.
const IntervalYM operator+(const IntervalYM &a,const IntervalYM &b
);
A year month interval.
Another year month interval.
This method assigns the sum of IntervalYM
and a
to IntervalYM
.
IntervalYM& operator+=(const IntervalYM &a);
This method sets the interval to the values specified.
void set(int year,int month);
0 to 99999999
0 to 11
This method sets the interval to null.
void setNull();
This method ...
string toText(unsigned int lfprec,const string &nlsParam = "") const;
The Map
class is used to store the mapping of the SQL structured type to C++ classes.
For each user defined type, the Object Type Translator (OTT) generates a C++ class declaration and implements the static methods readSQL()
and writeSQL()
. The readSQL()
method is called when the object from the server appears in the application as a C++ class instance. The writeSQL()
method is called to marshal the object in the application cache to server data when it is being written / flushed to the server. The readSQL()
and writeSQL()
methods generated by OTT are based upon the OCCI standard C++ mappings.
If you want to override the standard OTT generated mappings with customized mappings, you must implement a custom C++ class along with the readSQL()
and writeSQL()
methods for each SQL structured type you need to customize. In addition, you must add an entry for each such class into the Map
member of the Environment
.
To..., use the syntax:
Map();
Method | Summary |
---|---|
Adds a map entry for the type to be customized. |
This method adds a map entry for the type to be customized.
This method adds a map entry for the type, type_name, that you want to customize. You must implement the type_name C++ class along with its static methods, readSQL()
and writeSQL()
.
You must then add this information into a map object, which should be registered with the connection if the user wants the standard mappings to overridden.This registration can be done by calling the this method after the environment is created passing the environment.
void put(const string&, void *(*)(void *),void (*)(void *, void *));
A MetaData
object can be used to describe the types and properties of the columns in a ResultSet
or the existing schema objects in the database. It also provides information about the database as a whole.
Listing of the parameter types for objects:
Listing of attribute values:
These are returned on executing a get method passing some attribute for which these are the results.
To..., use the syntax:
MetaData(const MetaData &omd);
The source metadata object to be copied from.
This method returns the number of attributes related to the metadata object.
unsigned int getAttributeCount() const;
This method returns the attribute ID (ATTR_NUM_COLS,
. . . ) of the attribute represented by the attribute number specified.
AttrId getAttributeId(unsigned int attributenum) const;
The number of the attribute for which the attribute ID is to be returned.
This method returns the attribute type (NUMBER, INT, . . . ) of the attribute represented by attribute number specified.
Type getAttributeType(unsigned int attributenum) const;
The number of the attribute for which the attribute type is to be returned.
This method returns the value of the attribute as a C++ boolean. If the value is a SQL null, the result is false.
bool getBoolean(MetaData::AttrId attrid) const;
The attribute ID.
This method returns the value of the attribute as a C++ int. If the value is SQL null, the result is 0.
int getInt(MetaData::AttrId attrid) const;
The attribute ID .
This method returns a MetaData
instance holding the attribute value. A metadata attribute value can be retrieved as a MetaData
instance. This method can only be called on attributes of the metadata type.
MetaData getMetaData(MetaData::AttrId attrid) const;
The attribute ID.
This method returns the value of the attribute as a Number
object. If the value is a SQL null, the result is null.
Number getNumber(MetaData::AttrId attrid) const;
The attribute ID.
This method returns the value of the attribute as a RefAny
. If the value is SQL null, the result is null.
RefAny getRef(MetaData::AttrId attrid) const;
The attribute ID.
This method returns the value of the attribute as a string. If the value is SQL null, the result is null.
string getString(MetaData::AttrId attrid) const;
The attribute ID.
This method returns the value of the attribute as a Timestamp
object. If the value is a SQL null, the result is null.
Timestamp getTimestamp(MetaData::AttrId attrid) const;
The attribute ID.
This method returns the value of the attribute as a C++ unsigned int. If the value is a SQL null, the result is 0.
unsigned int getUInt(MetaData::AttrId attrid) const;
The attribute ID.
This method returns a C++ vector containing the attribute value. A collection attribute value can be retrieved as a C++ vector instance. This method can only be called on attributes of a list type.
vector<MetaData> getVector(MetaData::AttrId attrid) const;
The attribute ID.
void operator=(const MetaData &omd);
The Number
class handles limited-precision signed base 100 numbers. A Number
guarantees 38 decimal digits of precision. All positive numbers in the range displayed here can be represented to a full 38-digit precision:
10^-130
and
9.99999999999999999999999999999999999999*10^125
The range of representable negative numbers is symmetrical.
The number zero can be represented exactly. Also, Oracle numbers have representations for positive and negative infinity. These are generally used to indicate overflow.
The internal storage type is opaque and private. Scale is not preserved when Number
instances are created.
Number
does not support the concept of NaN and is not IEEE-754-85 compliant. Number
does support +Infinity and -Infinity.
There are several variants of syntax:
Default constructor.
Number(); Number(const Number &srcNum);
Translates a native long double into a Number
. The Number
is created using the precision of the platform-specific constant LDBL_DIG.
Number(long double val);
Translates a native double into a Number
. The Number
is created using the precision of the platform-specific constant DBL_DIG.
Number(double val);
Translates a native float into a Number
. The Number
is created using the precision of the platform-specific constant FLT_DIG.
Number(float val);
Translates a native long into a Number
.
Number(long val);
Translates a native int into a Number
.
Number(int val);
Translates a native short into a Number
.
Number(short val);
Translates a native char into a Number
.
Number(char val);
Translates an native unsigned long into a Number
.
Number(unsigned long val);
Translates a native unsigned int into a Number
.
Number(unsigned int val);
Translates a native unsigned short into a Number
.
Number(unsigned short val);
Translates the unsigned character array into a Number
.
Number(unsigned char val);
Objects from the Number
class can be used as standalone class objects in client side numerical computations. They can also be used to fetch from and set to the database.
The following code example demonstrates a Number
column value being retrieved from the database, a bind using a Number
object, and a comparison using a standalone Number
object:
/* Create a connection */ Environment *env = Environment::createEnvironment(Environment::DEFAULT); Connection *conn = env->createConnection(user, passwd, db); /* Create a statement and associate a select clause with it */ string sqlStmt = "SELECT department_id FROM DEPARTMENTS"; Statement *stmt = conn->createStatement(sqlStmt); /* Execute the statement to get a result set */ ResultSet *rset = stmt->executeQuery(); while(rset->next()) {Number deptId = rset->getNumber(1); /* Display the department id with the format string 9,999 */ cout << "Department Id" << deptId.toText(env, "9,999"); /* Use the number obtained as a bind value in the following query */ stmt->setSQL("SELECT * FROM EMPLOYEES WHERE department_id = :x"); stmt->setNumber(1, deptId); ResultSet *rset2 = stmt->executeQuery(); . . .} /* Using a Number object as a standalone and the operations on them */ /* Create a number to a double value */ double value = 2345.123; Number nu1 (value); /* Some common Number methods */ Number abs = nu1.abs(); /* absolute value */ Number sqrt = nu1.squareroot(); /* square root */ /* Cast operators can be used */ long lnum = (long) nu1; /* Unary increment/decrement prefix/postfix notation */ nu1++; --nu1; /* Arithmetic operations */ Number nu2(nu1); /* Assignment operators */ Number nu3; nu3 = nu2; nu2 = nu2 + 5.89; Number nu4; nu4 = nu1 + nu2; /* Comparison operators */ if(nu1>nu2) . . . else if(nu1 == nu2) . . .
This method returns the absolute value of the Number
object.
const Number abs() const;
This method returns the arccosine of the Number
object.
const Numberconst Number arcCos() const;
This method returns the arcsine of the Number
object.
const Number arcSin() const;
This method returns the arctangent of the Number
object.
const Number arcTan() const;
This method returns the arctangent of the Number
object divided by the value of the parameter specified.
const Number arcTan2(const Number &val) const
This method returns the smallest integer that is greater than or equal to the Number
object.
const Number ceil() const;
This method returns the cosine of the Number
object.
const Number cos() const;
This method returns the exponential of the Number
object.
const Number exp() const;
This method returns the largest integer that is less than or equal to the Number
object.
const Number floor() const;
This method returns a Number
object represented by the byte string specified.
void fromBytes(const Bytes &s);
A byte string.
This method returns a Number
object derived from a string value.
void fromText(const Environment *envp,const string &number, const string &fmt, const string &nlsParam = "");
The OCCI environment.
The number string to be converted to a Number
object.
Format string.
The nls parameters string. If nlsParam
is specified, this determines the nls parameters to be used for the conversion. If nlsParam
is not specified, the nls parameters are picked up from envp
.
This method returns the hypercosine of the Number
object.
const Number hypCos() const;
This method returns the hypersine of the Number
object.
const Number hypSin() const;
This method returns the hypertangent of the Number
object.
const Number hypTan() const;
This method returns a Number
whose value is (this^val).
const Number intPower(int val) const;
This method tests whether the Number
object is null. If the Number
object is null, then true is returned; otherwise, false is returned.
bool isNull() const;
This method returns the natural logorithm of the Number
object.
const Number ln() const;
This method returns the logorithm of the Number
object with the base provided by the parameter specified.
const Number log(const Number &val) const;
The base to be used in the logorithm calculation.
Unary operator++()
. This method returns the Number
object incremented by 1.
Number& operator++();
This method returns the Number
object incremented by the integer specified.
const Number operator++(int);
Unary operator--()
. This method returns the Number
object decremented by 1.
Number& operator--();
This method returns the Number
object decremented by the integer specified.
const Number operator--(int);
This method returns the product of the parameters specified.
Number operator*(const Number &a,const Number &b);
A number.
Another number.
This method returns the quotient of the parameters specified.
Number operator/(const Number ÷nd,const Number &divisor);
The number to be divided.
The number to divide by.
This method returns the remainder of the division of the parameters specified.
Number operator%(const Number &a,const Number &b);
A number interval.
Another number interval.
This method returns the sum of the parameters specified.
Number operator+(const Number &a,const Number &b);
A number.
Another number.
Unary operator-()
. This method returns the negated value of the Number
object.
const Number operator-();
This method returns the difference between the parameters specified.
Number operator-(const Number &subtrahend,const Number &subtractor);
The number to be reduced.
The number to be subtracted.
This method checks whether the first parameter specified is less than the second parameter specified. If the first parameter is less than the second parameter, then true is returned; otherwise, false is returned. If either parameter is equal to infinity, then false is returned.
bool operator<(const Number &a,const Number &b);
A parameter of type Number
.
Another parameter of type Number
.
This method checks whether the first parameter specified is less than or equal to the second parameter specified. If the first parameter is less than or equal to the second parameter, then true is returned; otherwise, false is returned.If either parameter
is equal to infinity, then false is returned.
bool operator<=(const Number &a,const Number &b);
A parameter of type Number
.
Another parameter of type Number
.
This method checks whether the first parameter specified is greater than the second parameter specified. If the first parameter is greater than the second parameter, then true is returned; otherwise, false is returned. If either parameter is equal to infinity, then false is returned.
bool operator>(const Number &a,const Number &b);
A parameter of type Number
.
Another parameter of type Number
.
This method checks whether the first parameter specified is greater than or equal to the second parameter specified. If the first parameter is greater than or equal to the second parameter, then true is returned; otherwise, false is returned.If either parameter is equal to infinity, then false is returned.
bool operator>=(const Number &a,const Number &b);
A parameter of type Number
.
Another parameter of type Number
.
This method checks whether the parameters specified are equal. If the parameters are equal, then true is returned; otherwise, false is returned. If either parameter is equal to +infinity or -infinity, then false is returned.
bool operator==(const Number &a,const Number &b);
A parameter of type Number
.
Another parameter of type Number
.
This method checks whether the first parameter specified is equal to the second parameter specified. If the parameters are not equal, true is returned; otherwise, false is returned.
bool operator!=(const Number &a,const Number &b);
A parameter of type Number
.
Another parameter of type Number
.
This method assigns the value of the parameter specified to the Number
object.
Number& operator=(const Number &a);
A parameter of type Number
.
This method multiplies the Number
object by the parameter specified, and assigns the product to the Number
object.
Number& operator*=(const Number &a);
A parameter of type Number
.
This method divides the Number
object by the parameter specified, and assigns the quotient to the Number
object.
Number& operator/=(const Number &a);
A parameter of type Number
.
This method divides the Number
object by the parameter specified, and assigns the remainder to the Number
object.
Number& operator%=(const Number &a);
A parameter of type Number
.
This method adds the Number object and the parameter specified, and assigns the sum to the Number
object.
Number& operator+=(const Number &a);
A parameter of type Number
.
This method subtracts the parameter specified from the Number
object, and assigns the difference to the Number
object.
Number& operator-=(const Number &a);
A parameter of type Number
.
This method returns the value of the Number object converted to a native char.
operator char() const;
This method returns the value of the Number
object converted to a native double.
operator double() const;
This method returns the value of the Number
object converted to a native float.
operator float() const;
This method returns the value of the Number
object converted to a native int.
operator int()const;
This method returns the value of the Number
object converted to a native long.
operator long() const;
This method returns the value of the Number
object converted to a native long double.
operator long double() const;
This method returns the value of the Number
object converted to a native short integer.
operator short() const;
This method returns the value of the Number
object converted to a native unsigned char.
operator unsigned char() const;
This method returns the value of the Number
object converted to a native unsigned integer.
operator unsigned int() const;
This method returns the value of the Number
object converted to a native unsigned long.
operator unsigned long() const;
This method returns the value of the Number
object converted to a native unsigned short integer.
operator unsigned short() const;
This method returns the value of the Number
object raised to the power provided by the parameter specified.
const Number power(const Number &val) const;
This method returns the value of the Number
object rounded to the digits of precision provided by the parameter specified.
const Number prec(int digits) const;
The number of digits of precision.
This method returns the value of the Number
object rounded to the decimal place provided by the parameter specified.
const Number round(int decplace) const;
The number of digits to the right of the decimal point.
This method sets the value of the Number
object to null.
void setNull();
This method returns the Number
object multiplied by 10 to the power provided by the parameter specified.
const Number shift(int val) const;
An integer value
This method returns the sign of the value of the Number
object. If the Number
object is negative, then -1 is returned. If the Number
object is equal to 0, then 0 is returned. If the Number
object is positive, then 1 is returned.
const int sign() const;
This method returns the sin of the Number
object.
const Number sin();
This method returns the square root of the Number
object.
const Number squareroot() const;
This method returns the tangent of the Number
object.
const Number tan() const;
This method converts the Number
object into a Bytes
object. The bytes representation is assumed to be in length excluded format, that is, the Byte.length()
method gives the length of valid bytes and the 0th byte is the exponent byte.
Bytes toBytes() const;
This method converts the Number
object to a formatted string based on the parameters specified.
string toText(const Environment *envp,const string &fmt, const string &nlsParam = "") const;
The OCCI environment.
The format string.
The nls parameters string. If nlsParam
is specified, this determines the nls parameters to be used for the conversion. If nlsParam
is not specified, the nls parameters are picked up from envp
.
This method returns the Number
object truncated at the number of decimal places provided by the parameter specified.
const Number trunc(int decplace) const;
The number of places to the right of the decimal place at which the value is to be truncated.
OCCI provides object navigational calls that enable applications to perform any of the following on objects:
This class enables the type definer to specify when a class is capable of having persistent or transient instances. Instances of classes derived from PObject
are either persistent or transient. A class (called "A") that is persistent-capable inherits from the PObject
class:
class A : PObject { ... }
Some of the methods provided, such as lock()
and refresh()
, are applicable only for persistent instances, not for transient instances.
To create a null Pobject
, use the syntax:
PObject();
The only methods valid on a null Pobject
are setNull()
, isNull
, and operator=()
.
To create a copy of a Pobject
, use the syntax:
PObject(const PObject& obj);
This method flushes a modified persistent object to the database server.
void flush();
This method returns the connection from which the persistent object was instantiated.
const Connection *getConnection() const;
This method returns a reference to the persistent object.
RefAny getRef() const;
This method test whether the persistent object is locked. If the persistent object is locked, then true is returned; otherwise, false is returned.
bool isLocked() const;
This method tests whether the persistent object is null. If the persistent object is null, then true is returned; otherwise, false is returned.
bool isNull() const;
This method locks a persistent object on the database server.
void lock(PObject::LockOption lock_option);
Specifies whether the lock operation should wait if the object is already locked by another user. The default value is OCCI_LOCK_WAIT
, meaning the operation will wait.
Valid values are:
OCCI_LOCK_WAIT
OCCI_LOCK_NOWAIT
This method marks a persistent object as deleted.
void markDelete();
This method marks a persistent object as modified or dirty.
void mark_Modified();
This method assigns the value of a persistent object this PObject
object. The nature (transient or persistent) of the object is maintained. Null information is copied from the source instance.
PObject& operator=(const PObject& obj);
The object to copy from.
This method is used to delete a persistent or transient object. The delete operator on a persistent object removes the object from the application cache only. To delete the object from the database server, invoke the markDelete()
method.
void operator delete(void *obj,size_t size);
The object instance to be deleted.
This method is used to create a new object. A persistent object is created if the connection and table name are provided. Otherwise, a transient object is created.
There are variants of syntax:
void *operator new(size_t size); void *operator new(size_t size,const Connection *x, const string& tablename, const char *type_name);
The connection to the database in which the persistent object is to be created.
The name of the table in the database server.
The SQL type name corresponding to this C++ class. The format is <schemaname>.<typename>
.
This method pins the object and increments the pin count by one. As long as the object is pinned, it will not be freed by the cache even if there are no references to this object instance.
void pin();
This method sets the object value to null.
void setNull();
This method unmarks a persistent object as modified or deleted.
void unmark();
This method unpins a persistent object. In the default mode, the pin count of the object is decremented by one. When this method is invoked with OCCI_PINCOUNT_RESET
, the pin count of the object is reset.
If the pin count is reset, this method invalidates all the references (Ref
) pointing to this object. The cache sets the object eligible to be freed, if necessary, reclaiming memory.
void unpin(UnpinOption mode=OCCI_PINCOUNT_DECR);
Specifies whether the pin count should be decremented or reset to 0.
Valid values are:
OCCI_PINCOUNT_RESET
OCCI_PINCOUNT_DECR
The mapping in the C++ programming language of an SQL REF value, which is a reference to an SQL structured type value in the database.
Each REF value has a unique identifier of the object it refers to. An SQL REF value may be used in place of the SQL structured type it references; it may be used as either a column value in a table or an attribute value in a structured type.
Because an SQL REF value is a logical pointer to an SQL structured type, a Ref object is by default also a logical pointer; thus, retrieving an SQL REF value as a Ref object does not materialize the attributes of the structured type on the client.
A Ref object can be saved to persistent storage and is de-referenced through operator*
or operator->
or ptr()
methods. T must be a class derived from PObject
. In the following sections, T* and PObject
* are used interchangeably.
To create a null Ref
object, use the syntax:
Ref();
The only methods valid on a null Ref
object are isNull
, and operator=()
.
To create a copy of a Ref
object, use the syntax:
Ref(const Ref<T> &src);
This method clears the Ref
object.
void clear();
This method returns the connection from which the Ref
object was instantiated.
const Connection *getConnection() const;
This method returns the OCI Ref from the Ref
object.
OCIRef *getRef() const;
This method test whether the Ref
object is null. If the Ref
object is null, then true is returned; otherwise, false is returned.
bool isNull() const;
This method marks the referenced object as deleted.
void markDelete();
This method dereferences the Ref
object and pins or fetches the referenced object if necessary. This might result in prefetching a graph of objects if prefetch attributes of the referenced object are set.
There are variants of syntax:
T * operator->();
const T * operator->() const;
This method dereferences the Ref
object and pins or fetches the referenced object if necessary. This might result in prefetching a graph of objects if prefetch attributes of the referenced object are set.
The object does not need to be deleted. Destructor would be automatically called when it goes out of scope.
There are variants of syntax:
T & operator *();
const T & operator*() const;
This method tests whether two Ref
objects are referencing the same object. If the Ref
objects are referencing the same object, then true is returned; otherwise, false is returned.
bool operator == (const Ref<T> &ref) const;
The Ref
object of the object to be compared.
This method tests whether two Ref
objects are referencing the same object. If the Ref
objects are not referencing the same object, then true is returned; otherwise, false is returned.
bool operator!= (const Ref<T> &ref) const;
The Ref
object of the object to be compared.
Assigns the ref or the object to a ref. For the first case, the refs are assigned and for the second case, the ref is constructed from the object and then assigned.
There are variants of syntax:
Ref<T>& operator=(const Ref<T> &src);
Ref<T>& operator=(const T *obj);
This operator dereferences the Ref and pins/fetches the object if necessary. This might result in prefetching a graph of objects if prefetch attributes of the Ref are set.
There are variants of syntax:
T * ptr();
const T * ptr() const;
Sets the prefetching options for the complex object retrieval.
This method specifies depth up to which all objects reachable from this object through Ref
s (transitive closure) should be prefetched. If only selected attribute types are to be prefetched, then setPrefetch
(type_name
, depth
) should be used.
This method specifies which Ref attributes of the object it refers to should be followed for prefetching of the objects (complex object retrieval) and how many levels deep those links should be followed.
There are variants of syntax:
void setPrefetch(const string &typeName,unsigned int depth);
void setPrefetch(unsigned int depth);
Type of the Ref attribute to be prefetched.
Depth level to which the links should be followed.
This method specifies how the object should be locked when dereferenced.
void setLock(LockOptions);
This method unmarks the referred object as dirty.
void unmarkDelete();
The RefAny
class is designed to support a reference to any type. Its primary purpose is to handle generic references and allow conversions of Ref
in the type hierarchy. A RefAny
object can be used as an intermediary between any two types, Ref<
x
>
and Ref<
y
>
, where x
and y
are different types.
A Ref<T>
can always be converted to a RefAny
; there is a method to perform the conversion in the Ref<T>
template. Each Ref<T>
has a constructor and assignment operator that takes a reference to RefAny
.
RefAny(); RefAny(const Connection *sessptr, const OCIRef *Ref); RefAny(const RefAny& src);
This method clears the reference.
void clear();
Returns the connection from which this ref was instantiated.
const Connection * getConnection() const;
Returns the underlying OCIRef *
OCIRef* getRef() const;
Returns true if the object pointed to by this ref is null else false.
bool isNull() const;
This method marks the referred object as deleted.
void markDelete();
Assigns the ref or the object to a ref. For the first case, the refs are assigned and for the second case, the ref is constructed from the object and then assigned.
RefAny& operator=(const RefAny& src);
Compares this ref with the Ref/RefAny object and returns true if both the refs are referring to the same object in the cache, otherwise it returns false.
bool operator== (const RefAny &refAnyR) const;
Compares this ref with the Ref/RefAny object and returns true if both the refs are not referring to the same object in the cache, otherwise it returns false.
bool operator!= (const RefAny &refAnyR) const;
This method unmarks the referred object as dirty.
void unmarkDelete();
A ResultSet
provides access to a table of data generated by executing a Statement
. Table rows are retrieved in sequence. Within a row, column values can be accessed in any order.
A ResultSet
maintains a cursor pointing to its current row of data. Initially the cursor is positioned before the first row. The next
method moves the cursor to the next row.
The get ... () methods retrieve column values for the current row. You can retrieve values either using the index number of the column or the name of the column. In general, using the column index is more efficient. Columns are numbered beginning at 1.
For the get ... () methods, OCCI attempts to convert the underlying data to the specified C++ type and returns a C++ value.
SQL types are mapped to C++ types with the ResultSet::get ... ()
methods.
The number, types and properties of a ResultSet's columns are provided by the MetaData object returned by the getColumnListMetaData method.
enum Status { END_OF_FETCH = 0, DATA_AVAILABLE, STREAM_DATA_AVAILABLE };
This is the ResultSet
constructor.
ResultSet()
This method cancels the result set.
void cancel();
This method closes the stream specified by the parameter stream
.
void closeStream(Stream *stream);
The stream to be closed.
This method returns the value of a column in the current row as a Bfile
. Returns the column value; if the value is SQL null, the result is false
.
Bfile getBfile(unsigned int colIndex);
The first column is 1, the second is 2, . . . .
Get the value of a column in the current row as an Blob
. Returns the column value; if the value is SQL null, the result is false
.
Blob getBlob(unsigned int colIndex);
The first column is 1, the second is 2, . . . .
Get the value of a column in the current row as a Bytes
array. The bytes represent the raw values returned by the server. Returns the column value; if the value is SQL null, the result is null array
Bytes getBytes(unsigned int colIndex);
The first column is 1, the second is 2, . . . .
Get the character set in which data would be fetched.
CharSet getCharSet(unsigned int colIndex) const;
The first column is 1, the second is 2, . . . .
Get the value of a column in the current row as a Clob
. Returns the column value; if the value is SQL null, the result is false
.
Clob getClob(unsigned int colIndex);
The first column is 1, the second is 2, . . . .
The number, types and properties of a ResultSet
's columns are provided by the getMetaData
method. Returns the description of a ResultSet
's columns. This method will return the value of the given column as a PObject
. The type of the C++ object will be the C++ PObject
type corresponding to the column's SQL type registered with Environment
's map. This method is used to materialize data of SQL user-defined types.
vector<MetaData> getColumnListMetaData() const;
If the result set has any input Stream
parameters, this method returns the column index of the current input Stream
that must be read. If no output Stream
needs to be read, or there are no input Stream
columns in the result set, this method returns 0. Returns the column index of the current input Stream
column that must be read.
unsigned int getCurrentStreamColumn() const;
If the result has any input Stream
s, this method returns the current row of the result set that is being processed by OCCI. If this method is called after all the rows in the set of array of rows have been processed, it returns 0. Returns the row number of the current row that is being processed. The first row is numbered 1 and so on.
unsigned int getCurrentStreamRow() const;
Get the nested cursor as an ResultSet
. Data can be fetched from this result set. A nested cursor results from a nested query with a CURSOR(SELECT ... ) clause.
SELECT ename, CURSOR(SELECT dname, loc FROM dept) FROM emp WHERE ename = 'JONES'
Note that if there are multiple REF
CURSOR
s being returned, data from each cursor must be completely fetched before retrieving the next REF
CURSOR
and starting fetch on it. Returns A ResultSet
for the nested cursor.
ResultSet * getCursor(unsigned int colIndex);
The first column is 1, the second is 2, . . . .
Get the value of a column in the current row as a Date
object. Returns the column value; if the value is SQL null, the result is null
Date getDate(unsigned int colIndex);
The first column is 1, the second is 2, . . . .
Gets the value of a column in the current row as a C++ double. Returns the column value; if the value is SQL null, the result is 0
double getDouble(unsigned int colIndex);
The first column is 1, the second is 2, . . . .
Get the value of a column in the current row as a C++ float. Returns the column value; if the value is SQL null, the result is 0.
float getFloat(unsigned int colIndex);
The first column is 1, the second is 2, . . . .
Get the value of a column in the current row as a C++ int. Returns the column value; if the value is SQL null, the result is 0.
int getInt(unsigned int colIndex);
The first column is 1, the second is 2, . . . .
Get the value of a column in the current row as a IntervalDS
object. Returns the column value; if the value is SQL null, the result is null.
IntervalDS getIntervalDS(unsigned int colIndex);
The first column is 1, the second is 2, . . . .
Get the value of a column in the current row as a IntervalYM
object. Returns the column value; if the value is SQL null, the result is null
IntervalYM getIntervalYM(unsigned int colIndex);
The first column is 1, the second is 2, . . . .
Get the maximum amount of data to read for a column.
unsigned int getMaxColumnSize(unsigned int colIndex) const;
The first column is 1, the second is 2, . . . .
Returns the actual number of rows fetched in the last array fetch when next(int numRows) returned END_OF_DATA
. Returns the actual number of rows fetched in the final array fetch
unsigned int getNumArrayRows() const;
Get the value of a column in the current row as a Number
object. Returns the column value; if the value is SQL null, the result is null
Number getNumber(unsigned int colIndex);
The first column is 1, the second is 2, . . . .
Returns a pointer to a PObject
holding the column value.
PObject * getObject(unsigned int colIndex);
The first column is 1, the second is 2, . . . .
Get the value of a column in the current row as a RefAny
. Retrieving a Ref
value does not materialize the data to which Ref
refers. Also the Ref
value remains valid while the session or connection on which it is created is open. Returns a RefAny
holding the column value.
RefAny getRef(unsigned int colIndex);
The first column is 1, the second is 2, . . . .
Get the current rowid for a SELECT
... FOR
UPDATE
statement. The rowid can be bound to a prepared DELETE
statement and so on. Returns Current rowid for a SELECT
... FOR
UPDATE
statement.
Bytes getRowid(unsigned int colIndex);
The first column is 1, the second is 2, . . . .
Get the Rowid of the current row position.
Bytes getRowPosition() const
This method returns the Statement
of the ResultSet
.
const Statement* getStatement() const;
This method returns the value of a column in the current row as a Stream
.
Stream * getStream(unsigned int colIndex);
The first column is 1, the second is 2, . . . .
Get the value of a column in the current row as a string. Returns the column value; if the value is SQL null, the result is an empty string.
string getString(unsigned int colIndex);
The first column is 1, the second is 2, . . . .
Get the value of a column in the current row as a Timestamp object. Returns the column value; if the value is SQL null, the result is null.
Timestamp getTimestamp(unsigned int colIndex);
The first column is 1, the second is 2, . . . .
Get the value of a column in the current row as a C++ int. Returns the column value; if the value is SQL null, the result is 0.
unsigned int getUInt(unsigned int colIndex);
The first column is 1, the second is 2, . . . .
This method returns the attribute in the current position as a vector of objects. It retrieves the column in the specified position as a vector of RefAny
. The attribute at the current position should be a collection type (varray
or nested table). The SQL type of the elements in the collection should be compatible with objects.
There are variants of syntax:
void getVector(ResultSet *rs,unsigned int index, vector<int> &vect);
void getVector(ResultSet *rs,unsigned int index, vector<string> &vect);
void getVector(ResultSet *rs,unsigned int index, vector<T *> &vect);
void getVector(ResultSet *rs,unsigned int, vector<unsigned int> &vect);
void getVector(ResultSet *rs,unsigned int, vector<float> &vect);
void getVector(ResultSet *rs,unsigned int, vector<double> &vect);
void getVector(ResultSet *rs,unsigned int, vector<Date> &vect);
void getVector(ResultSet *rs,unsigned int, vector<Timestamp> &vect);
void getVector(ResultSet *rs,unsigned int, vector<RefAny> &vect);
void getVector(ResultSet *rs,unsigned int, vector<Blob> &vect);
void getVector(ResultSet *rs,unsigned int, vector<Clob> &vect);
void getVector(ResultSet *rs,unsigned int, vector<Bfile> &vect);
void getVector(ResultSet *rs,unsigned int, vector<Number> &vect);
void getVector(ResultSet *rs,unsigned int, vector<IntervalDS> &vect);
void getVector(ResultSet *rs,unsigned int, vector<IntervalYM> &vect);
void getVector(ResultSet *rs,unsigned int, vector<Ref<T>> &vect);
The result set.
The reference to the vector of objects (OUT parameter).
A column may have the value of SQL null; wasNull()
reports whether the last column read had this special value. Note that you must first call get
xxx
on a column to try to read its value and then call wasNull
() to find if the value was the SQL null. Returns true
if last column read was SQL null.
bool isNull(unsigned int colIndex) const;
The first column is 1, the second is 2, . . . .
This method checks whether the value of the parameter is truncated. If the value of the parameter is truncated, then true is returned; otherwise, false is returned.
bool isTruncated(unsigned int paramIndex) const;
The first parameter is 1, the second is 2, . . . .
A ResultSet
is initially positioned before its first row; the first call to next makes the first row the current row; the second call makes the second row the current row, and so on. If a read-able stream from the previous row is open, it is implicitly closed. The ResultSet's
warning chain is cleared when a new row is read.
For non-streamed mode, next() always returns RESULT_SET_AVAILABLE
or END_OF_DATA
. Data is available for get
xxx
method when the RESULT_SET_AVAILABLE
status is returned. When this version of next()
is used, array fetches are done for data being fetched with the setDataBuffer()
interface. This means that get
xxx
()
methods should not be called. The numRows
amount of data for each column would materialize in the buffers specified with the setDataBuffer()
interface. With array fetches, stream input is allowed, so get
xxx
Stream()
methods can also be called (once for each column).
Returns one of following:
DATA_AVAILABLE
-- call get
xxx
()
or read data from buffers specified with setDataBuffer()
END_OF_FETCH
-- no more data available. This is the last set of rows for array fetches. This value is defined to be 0.
STREAM_DATA_AVAILABLE
-- call the getCurrentStreamColumn
method and read stream
Status next(unsigned int numRows =1);
Number of rows to fetch for array fetches
int preTruncationLength(unsigned int paramIndex) const;
The first parameter is 1, the second is 2, . . . .
Defines that a column is to be returned as a binary stream by the getStream
method.
void setBinaryStreamMode(unsigned int colIndex,unsigned int size);
The first column is 1, the second is 2, . . . .
Defines that a column is to be returned as a character stream by the getStream
method.
void setCharacterStreamMode(unsigned int colIndex,unsigned int size);
The first column is 1, the second is 2, . . . .
Overrides the default character set for the specified column. Data is converted from the database character set to the specified character set for this column.
void setCharSet(unsigned int colIndex,CharSet charSet);
The first column is 1, the second is 2, . . . .
Desired character set.
Specify a data buffer where data would be fetched. The buffer
parameter is a pointer to a user allocated data buffer. The current length of data must be specified in the *length
parameter. The amount of data should not exceed the size
parameter. Finally, type
is the data type of the data. Only non OCCI and non C++ specific types can be used i.e STL string, OCCI classes like Bytes and
Date
cannot be used.
If setDataBuffer
() is used to fetch data for array fetches, it should be called only once for each result set. Data for each row is assumed to be at buffer + (i - 1)*
size location where i
is the row number. Similarly the length of the data would be assumed to be at *(length + (i - 1)).
void setDataBuffer(unsigned int colIndex,void *buffer, Type type, sb4 size = 0, ub2 *length =NULL
, sb2 *ind =NULL
, ub2 *rc =NULL
);
The first column is 1, the second is 2, . . . .
Pointer to user-allocated buffer; if array fetches are done, it should have numRows
* size bytes in it
Type of the data that is provided (or retrieved) in the buffer
Size of the data buffer; for array fetches, it is the size of each element of the data items
Pointer to the length of data in the buffer; for array fetches, it should be an array of length data for each buffer element; the size of the array should be equal to arrayLength
This method enables/disables exceptions for reading of null
values on colIndex
column of the result set.
void setErrorOnNull(unsigned int colIndex,bool causeException);
The first column is 1, the second is 2, . . . .
Enable exceptions if true
. Disable if false
This method enables/disables exceptions when truncation occurs.
void setErrorOnTruncate(unsigned int paramIndex,bool causeException);
The first parameter is 1, the second is 2, . . . .
Enable exceptions if true
. Disable if false
Set the maximum amount of data to read for a column
void setMaxColumnSize(unsigned int colIndex,unsigned int max);
The first column is 1, the second is 2, . . . .
Returns the current status of the result set. The status method can be called repeatedly to find out the status of the result. Data is available for get
xxx
method when the RESULT_SET_AVAILABLE
status is returned. Returns one of following:
DATA_AVAILABLE
-- call get
xxx
()
or read data from buffers specified with the setDataBuffer
method
STREAM_DATA_AVAILABLE
-- call getCurrentStream()
and read stream
END_OF_FETCH
Status status() const;
The SQLException
class provides information on generated errors, their codes and associated messages.
This is the SQLException
constructor.
There are variants of syntax:
SQLException(); SQLException(const SQLException &e);
Method | Summary |
---|---|
Return the database error code. |
|
Return the error message string for this exception. |
|
Set the error context. |
Gets the database error code.
int getErrorCode() const;
Returns the error message string of this SQLException
if it was created with an error message string. Returns null if the SQLException
was created with no error message.
string getMessage() const;
Sets the pointer to the error context.
void setErrorCtx(void *ctx);
The pointer to the error context.
A Statement
object is used for executing SQL statements. The statement may be a query returning result set or a non-query statement returning an update count.
Non-query SQL can be insert, update, or delete statements. Non-query SQL statements can also be DDL statements (such as create, grant, and so on) or stored procedure calls.
A query, insert / update / delete, or stored procedure call statements may have IN bind parameters. A DML returning insert / update / delete statement or stored procedure call may have OUT bind parameters. Finally, a stored procedure call statement may have bind parameters that are both IN and OUT, referred to as IN/OUT parameters.
The Statement
class methods are divided into three categories:
Statement
methods applicable to all statements
To..., use the syntax:
Statement() enum Status { UNPREPARED, PREPARED, RESULT_SET_AVAILABLE, UPDATE_COUNT_AVAILABLE, NEEDS_STREAM_DATA, STREAM_DATA_AVAILABLE };
After specifying set parameters, an iteration is added for execution.
void addIteration();
In many cases, it is desirable to immediately release a result set's database and OCCI resources instead of waiting for this to happen when it is automatically closed; the closeResultSet
method provides this immediate release.
void closeResultSet(ResultSet *resultSet);
Closes the stream specified by the parameter stream
.
void closeStream(Stream *stream);
The stream to be closed.
Executes a SQL statement that may return either a result set or an update count. The statement may have read-able streams which may have to be written, in which case the results of the execution may not be readily available. The returned value is one of the following:
UNPREPARED
PREPARED
RESULT_SET_AVAILABLE
UPDATE_COUNT_AVAILABLE
NEEDS_STREAM_DATA
STREAM_DATA_AVAILABLE
If RESULT_SET_AVAILABLE
is returned, the getResultSet()
method must be called to get the result set.
If UPDATE_COUNT_AVAILABLE
is returned, the getUpdateCount
method must be called to find out the update count.
If NEEDS_STREAM_DATA
is returned, output Streams
must be written for the streamed IN
bind parameters. If there is more than one streamed parameter, call the getCurrentStreamParam
method to find out the bind parameter needing the stream. If the statement is executed iteratively, call getCurrentIteration
to find out the iteration for which stream needs to be written.
If STREAM_DATA_AVAILABLE
is returned, input Streams
must be read for the streamed OUT
bind parameters. If there is more than one streamed parameter, call the getCurrentStreamParam
method to find out the bind parameter needing the stream. If the statement is executed iteratively, call getCurrentIteration
to find out the iteration for which stream needs to be read.
If only one OUT
value is returned for each invocation of the DML returning statement, iterative executes can be performed for DML returning statements. If output streams are used for OUT
bind variables, they must be completely read in order. The getCurrentStreamParam
method would indicate which stream needs to be read. Similarly, getCurrentIteration
would indicate the iteration for which data is available.
Returns
RESULT_SET_AVAILABLE
-- call getResultSet()
UPDATE_COUNT_AVAILABLE
-- call getUpdateCount()
NEEDS_STREAM_DATA
-- call getCurrentStream()
and getCurrentIteration()
, and write
(or read
) stream
Status execute(const string &sql = "");
Executes insert/update/delete statements which use only the setDataBuffer() or stream interface for bind parameters. The bind parameters must be arrays of size arrayLength parameter. The statement may have read-able streams which may have to be written. The returned value is one of the following:
If UPDATE_COUNT_AVAILABLE
is returned, getUpdateCount()
must be called to find out the update count.
If NEEDS_STREAM_DATA
is returned, output Streams
must be written for the streamed bind parameters. If there is more than one streamed parameter, getCurrentStreamParam()
can be called to find out the bind parameter needing the stream. The getCurrentIteration()
can be called to find out the iteration for which stream needs to be written.
If STREAM_DATA_AVAIALBE
is returned, input Streams
must be read for the streamed OUT
bind parameters. If there is more than one streamed parameter, getCurrentStreamParam()
can be called to find out the bind parameter needing the stream. If the statement is executed iteratively, getCurrentIteration()
can be called to find out the iteration for which stream needs to be read.
If only one OUT
value is returned for each invocation of the DML returning statement, array executes can be done for DML returning statements also. If output streams are used for OUT
bind variables, they must be completely read in order. The getCurrentStreamParam()
method would indicate which stream needs to be read. Similarly, getCurrentIteration()
would indicate the iteration for which data is available.
Note that you cannot perform array executes for queries or callable statements.
Status executeArrayUpdate(unsigned int arrayLength);
The number of elements provided in each buffer of bind variables. The statement is executed this many times with each array element used for each iteration. Returns:
UPDATE_COUNT_AVAILABLE
-- call getUpdateCount()
NEEDS_STREAM_DATA
-- call getCurrentStream()
and getCurrentIteration()
, and write
(or read
) stream
Execute a SQL statement that returns a ResultSet
. Should not be called for a statement which is not a query, has streamed parameters. Returns a ResultSet
that contains the data produced by the query
ResultSet * executeQuery(const string &sql = "");
Executes a non-query statement such as a SQL INSERT
, UPDATE
, DELETE
statement, a DDL statement such as CREATE
/ALTER
and so on, or a stored procedure call. Returns either the row count for INSERT
, UPDATE
or DELETE
or 0 for SQL statements that return nothing
unsigned int executeUpdate(const string &sql = "");
Get the current auto-commit state. Returns Current state of auto-commit mode.
bool getAutoCommit() const;
Get the value of a BFILE
parameter as a Bfile
object. Returns the parameter value.
Bfile getBfile(unsigned int paramIndex);
The first parameter is 1, the second is 2, . . . .
Get the value of a BLOB
parameter as a Blob
. Returns the parameter value
Blob getBlob(unsigned int paramIndex);
The first parameter is 1, the second is 2, . . . .
Get the value of a SQL BINARY or VARBINARY
parameter as Bytes
. Returns the parameter value; if the value is SQL null, the result is null.
Bytes getBytes(unsigned int paramIndex);
The first parameter is 1, the second is 2, . . . .
Returns the character set that is in effect for the specified parameter.
CharSet getCharSet(unsigned int paramIndex) const;
The first parameter is 1, the second is 2, . . . .
Get the value of a CLOB
parameter as a Clob
. Returns the parameter value.
Clob getClob(unsigned int paramIndex);
The first parameter is 1, the second is 2, . . . .
const Connection* getConnection() const;
If the prepared statement has any output Streams
, this method returns the current iteration of the statement that is being processed by OCCI. If this method is called after all the invocations in the set of iterations has been processed, it returns 0. Returns the iteration number of the current iteration that is being processed. The first iteration is numbered 1 and so on. If the statement has finished execution, a 0 is returned.
unsigned int getCurrentIteration() const;
Returns the current param stream for which data is available
unsigned int getCurrentStreamIteration() const;
If the prepared statement has any output Stream
parameters, this method returns the parameter index of the current output Stream
that must be written. If no output Stream
needs to be written, or there are no output Stream
parameters in the prepared statement, this method returns 0.
Returns the parameter index of the current output Stream
parameter that must be written.
unsigned int getCurrentStreamParam() const;
Get the REF
CURSOR
value of an OUT
parameter as a ResultSet
. Data can be fetched from this result set. The OUT
parameter must be registered as CURSOR
with the OCCICallableStatement
.registerOutParameter
(int
paramIndex
, CURSOR
) method. Note that if there are multiple REF
CURSORs
being returned due to a batched call, data from each cursor must be completely fetched before retrieving the next REF
CURSOR
and starting fetch on it. Returns A ResultSet
for the OUT
parameter value.
ResultSet * getCursor(unsigned int paramIndex);
The first parameter is 1, the second is 2, . . . .
Get whether this data is for an NCHAR
parameter. Returns whether data is in NCHAR
character set. Returns true
if NCHAR
parameter; false
otherwise
bool getDatabaseNCHARParam(unsigned int paramIndex) const;
The first parameter is 1, the second is 2, . . . .
Get the value of a SQL DATE
parameter as a Date
object. Returns the parameter value; if the value is SQL null, the result is null.
Date getDate(unsigned int paramIndex) const;
the first parameter is 1, the second is 2, . . . .
Get the value of a DOUBLE
parameter as a C++ double. Returns the parameter value; if the value is SQL null, the result is 0.
double getDouble(unsigned int paramIndex);
The first parameter is 1, the second is 2, . . . .
Get the value of a FLOAT parameter as a C++ float. Returns the parameter value; if the value is SQL null, the result is 0.
float getFloat(unsigned int paramIndex);
The first parameter is 1, the second is 2, . . . .
Get the value of an INTEGER
parameter as a C++ int. Returns the parameter value; if the value is SQL null
, the result is 0
unsigned int getInt(unsigned int paramIndex);
The first parameter is 1, the second is 2, . . . .
Get the value of a parameter as a IntervalDS
object.
IntervalDS getIntervalDS(unsigned int paramIndex);
The first parameter is 1, the second is 2, . . . .
Get the value of a parameter as a IntervalYM
object.
IntervalYM getIntervalYM(unsigned int paramIndex);
The first parameter is 1, the second is 2, . . . .
Gets the current limit on maximum number of iterations. Default is 1. Returns the current maximum number of iterations.
unsigned int getMaxIterations() const;
The maxParamSize
limit (in bytes) is the maximum amount of data sent or returned for any parameter value; it only applies to character and binary types. If the limit is exceeded, the excess data is silently discarded. Returns the current max parameter size limit
unsigned int getMaxParamSize(unsigned int paramIndex) const;
The first parameter is 1, the second is 2, . . . .
Get the value of a NUMERIC
parameter as a Number
object. Returns the parameter value; if the value is SQL nullnull
, the result is null.
Number getNumber(unsigned int paramIndex);
The first parameter is 1, the second is 2, . . . .
Get the value of a parameter as a PObject
. This method returns an PObject
whose type corresponds to the SQL type that was registered for this parameter using registerOutParameter
. Note that this method may be used to read database-specific, abstract data types. Returns A PObject
holding the OUT
parameter value.
PObject * getObject(unsigned int paramIndex);
The first parameter is 1, the second is 2, . . . .
Get the OCI statement handle associated with the Statement
. Returns the OCI statement handle associated with the Statement
OCIStmt * getOCIStatement() const;
Get the value of a REF
parameter as RefAny
. Returns the parameter value.
RefAny getRef(unsigned int paramIndex);
The first parameter is 1, the second is 2, . . . .
Returns the current result as a ResultSet
.
ResultSet * getResultSet();
Get the rowid
param value as a Bytes
Bytes getRowid(unsigned int paramIndex);
The first parameter is 1, the second is 2, . . . .
Returns the current SQL string associated with the Statement object.
string getSQL() const;
Stream * getStream(unsigned int paramIndex);
The first parameter is 1, the second is 2, . . . .
Get the value of a CHAR
, VARCHAR
, or LONGVARCHAR
parameter as an string. Returns the parameter value; if the value is SQL null
, the result is empty string.
string getString(unsigned int paramIndex);
The first parameter is 1, the second is 2, . . . .
Get the value of a SQL TIMESTAMP parameter as a Timestamp object. Returns the parameter value; if the value is SQL null
, the result is null
Timestamp getTimestamp(unsigned int paramIndex);
The first parameter is 1, the second is 2, . . . .
Get the value of a BIGINT
parameter as a C++ unsigned int. Returns the parameter value; if the value is SQL null
, the result is 0
unsigned int getUInt(unsigned int paramIndex);
The first parameter is 1, the second is 2, . . . .
Returns the current result as an update count.
unsigned int getUpdateCount() const;
This method returns the attribute in the current position as a vector of objects. It retrieves the column in the specified position as a vector of RefAny
. The attribute at the current position should be a collection type (varray
or nested table). The SQL type of the elements in the collection should be compatible with objects.
There are variant of syntax:
void getVector(Statement *stmt,unsigned int index, vector<int> &vect;
void getVector(Statement *stmt,unsigned int index, vector<string> &vect;
void getVector(Statement *stmt,unsigned int index, vector<T *> &vect;
void getVector(Statement *stmt,unsigned int, vector<unsigned int> &vect;
void getVector(Statement *stmt,unsigned int, vector<float> &vect;
void getVector(Statement *stmt,unsigned int, vector<double> &vect;
void getVector(Statement *stmt,unsigned int, vector<Date> &vect;
void getVector(Statement *stmt,unsigned int, vector<Timestamp> &vect;
void getVector(Statement *stmt,unsigned int, vector<RefAny> &vect;
void getVector(Statement *stmt,unsigned int, vector<Blob> &vect;
void getVector(Statement *stmt,unsigned int, vector<Clob> &vect;
void getVector(Statement *stmt,unsigned int, vector<Bfile> &vect;
void getVector(Statement *stmt,unsigned int, vector<Number> &vect;
void getVector(Statement *stmt,unsigned int, vector<IntervalDS> &vect;
void getVector(Statement *stmt,unsigned int, vector<IntervalYM> &vect;
void getVector(Statement *stmt,unsigned int, vector<Ref<T>> &vect;
The result set.
The reference to the vector of objects (OUT parameter).
An OUT
parameter may have the value of SQL null
; wasNull
reports whether the last value read has this special value. Note that you must first call getXXX
on a parameter to read its value and then call wasNull() to see if the value was SQL null
. Returns true
if the last parameter read was SQL null
bool isNull(unsigned int paramIndex ) const;
The first parameter is 1, the second is 2, . . . .
This method checks whether the value of the parameter is truncated. If the value of the parameter is truncated, then true is returned; otherwise, false is returned.
bool isTruncated(unsigned int paramIndex) const;
The first parameter is 1, the second is 2, . . . .
int preTruncationLength(unsigned int paramIndex) const;
The first parameter is 1, the second is 2, . . . .
This method registers the type
of each out
paramater of a PL/SQL stored procedure. Before executing a PL/SQL stored procedure, you must explicitly call this method to register the type
of each out
parameter. This method should be called for out
parameters only. Use the set
xxx
method for in/out parameters.
When reading the value of an out
parameter, you must use the get
xxx
method that corresponds to the parameter's registered SQL type. For example, use getInt
or getNumber
when OCCIINT
or OCCINumber
is the type specified.
If a PL/SQL stored procedure has an out
paramater of type
ROWID
, the type
specified in this method should be OCCISTRING
. The value of the out
parameter can then be retrieved by calling the getString()
method.
If a PL/SQL stored procedure has an in/out parameter of type ROWID
, call the methods setString()
and getString()
to set the type and retrieve the value of the in/out parameter.
void registerOutParam(unsigned int paramIndex,Type type, unsigned int maxSize = 0, const string &sqltype = "");
The first parameter is 1, the second is 2, . . . .
SQL type code defined by type
; only datatypes corresponding to OCCI data types such as Date
, Bytes
, and so on.
The maximum size of the retrieved value. For datatypes of OCCIBYTES
and OCCISTRING
, maxSize
should be greater than 0.
The name of the type in the data base (used for types which have been created with CREATE
TYPE
)
A Statement
can be in auto-commit mode. In this case any statement executed is also automatically committed. By default, the auto-commit mode is turned-off.
void setAutoCommit(bool autoCommit);
True
enables auto-commit; false
disables auto-commit.
Set a parameter to a Bfile
value.
void setBfile(unsigned int paramIndex,const Bfile &x);
The first parameter is 1, the second is 2, . . . .
The parameter value.
Defines that a column is to be returned as a binary stream by the getStream
method.
void setBinaryStreamMode(unsigned int colIndex,unsigned int size);
The first column is 1, the second is 2, . . . .
Set a parameter to a Blob
value.
void setBlob(unsigned int paramIndex,const Blob &x);
The first parameter is 1, the second is 2, . . . .
The parameter value.
Set a parameter to a Bytes
array.
void setBytes(unsigned int paramIndex,const Bytes &x);
The first parameter is 1, the second is 2, . . . .
The parameter value.
Defines that a column is to be returned as a character stream by the getStream
method.
void setCharacterStreamMode(unsigned int colIndex,unsigned int size);
The first column is 1, the second is 2, . . . .
Overrides the default character set for the specified parameter. Data is assumed to be in the specified character set and is converted to database character set. For OUT binds of OCICallableStatements
, this specifies the character set to which database characters are converted to.
void setCharSet(unsigned int paramIndex,CharSet charSet);
The first parameter is 1, the second is 2, . . . .
Selected character set.
Set a parameter to a Clob
value.
void setClob(unsigned int paramIndex,const Clob &x);
The first parameter is 1, the second is 2, . . . .
The parameter value.
Set a parameter to a Date
value.
void setDate(unsigned int paramIndex,const Date &x);
The first parameter is 1, the second is 2, . . . .
The parameter value.
If the parameter is going to be inserted in a column that contains data in the database's NCHAR
character set, then OCCI must be informed by passing a true
value. A false
can be passed to restore the dafault.Returns returns the character set that is in effect for the specified parameter.
void setDatabaseNCHARParam(unsigned int paramIndex,bool isNCHAR);
The first parameter is 1, the second is 2, . . . .
True
if this parameter contains data in Database's NCHAR
character set; false
otherwise.
Specify a data buffer where data would be available. Also, used for OUT
bind parameters of callable statements (and DML returning OUT
binds in future).
The buffer
parameter is a pointer to a user allocated data buffer. The current length of data must be specified in the *length
parameter. The amount of data should not exceed the size
parameter. Finally, type
is the data type of the data.
Note that not all types
can be supplied in the buffer. For example, all OCCI allocated types (such as Bytes
, Date
and so on.) cannot be provided by the setDataBuffer
interface. Similarly, C++ Standard Library strings cannot be provided with the setDataBuffer
interface either. The type
can be any of OCI data types such VARCHAR2
, CSTRING
, CHARZ
and so on.
If setDataBuffer
() is used to specify data for iterative or array executes, it should be called only once in the first iteration only. For subsequent iterations, OCCI would assume that data is at buffer + i*size
location where i is the iteration number. Similarly the length of the data would be assumed to be at *(length + i)
.
void setDataBuffer(unsigned int paramIndex,void *buffer, Type type, sb4 size, ub2 *length, sb2 *ind =NULL
, ub2 *rc=NULL
);
The first parameter is 1, the second is 2, . . . .
Pointer to user-allocated buffer; if iterative or array executes are done, it should have numIterations * size bytes in it.
Type of the data that is provided (or retrieved) in the buffer
Size of the data buffer; for iterative and array executes, it is the size of each element of the data items
Pointer to the length of data in the buffer; for iterative and array executes, it should be an array of length data for each buffer element; the size of the array should be equal to arrayLength.
Indicator. For iterative and array executes, an indicator for every buffer element
Return code -- for iterative and array executes, a return code for every buffer element
Specify an array of data buffers where data would be available for reading or writing. Used for IN
, OUT
, and IN/OUT
bind parameters for stored procedures which read/write array parameters.
A stored procedure can have an array of values for IN
, IN/OUT
, or OUT
parameters. In this case, the parameter must be specified using the setDataBufferArray
() method. The array is specified just as for the setDataBuffer()
method for iterative or array executes, but the number of elements in the array is determined by *arrayLength
parameter.
For OUT
and IN/OUT
parameters, the maximum number of elements in the array is specified by the arraySize
parameter. Note that for iterative prepared statements, the number of elements in the array is determined by the number of iterations, and for array executes the number of elements in the array is determined by the arrayLength
parameter of the executeArrayUpdate
() method. However, for array parameters of stored procedures, the number of elements in the array must be specified in the *arrayLength
parameter of the setDataBufferArray()
method because each parameter may have a different size array.
This is different from prepared statements where for iterative and array executes, the number of elements in the array for each parameter is the same and is determined by the number of iterations of the statement, but a callable statement is executed only once, and each of its parameter can be a varying length array with possibly a different length.
Note that for OUT
and IN/OUT
binds, the number of elements returned in the array is returned in *arrayLength
as well. The client must make sure that it has allocated elementSize * arraySize
bytes for the buffer
.
void setDataBufferArray(unsigned int paramIndex,void *buffer, Type type, ub4 arraySize, ub4 *arrayLength, sb4 elementSize, ub2 *elementLength, sb2 *ind =NULL
, ub2 *rc =NULL
);
The first parameter is 1, the second is 2, . . . .
Pointer to user-allocated buffer. It should have size * arraySize
bytes in it
Type of the data that is provided (or retrieved) in the buffer
Maximum number of elements in the array
Pointer to number of current elements in the array
Size of the data buffer for each element
Pointer to an array of lengths. elementLength[i]
has the current length of the ith element of the array
Set a parameter to a C++ double value.
void setDouble(unsigned int paramIndex,double x);
The first parameter is 1, the second is 2, . . . .
The parameter value.
Enables/disables exceptions for reading of null
values on paramIndex parameter of the statement. If exceptions are enabled, calling a get
xxx
on paramIndex
parameter would result in an SQLException
if the parameter value is null. This call can also be used to disable exceptions.
void setErrorOnNUll(unsigned int paramIndex,bool causeException);
The first parameter is 1, the second is 2, . . . .
Enable exceptions if true
, disable if false
This method enables/disables exceptions when truncation occurs.
void setErrorOnTruncate(unsigned int paramIndex,bool causeException);
The first parameter is 1, the second is 2, . . . .
Enable exceptions if true
. Disable if false
Set a parameter to a C++ float value.
void setFloat(unsigned int paramIndex,float x);
The first parameter is 1, the second is 2, . . . .
The parameter value.
Set a parameter to a C++ int value.
void setInt(unsigned int paramIndex,int x);
The first parameter is 1, the second is 2, . . . .
The parameter value.
Set a parameter to a IntervalDS
value.
void setIntervalDS(unsigned int paramIndex,const IntervalDS &x);
The first parameter is 1, the second is 2, . . . .
The parameter value.
Set a parameter to a Interval
value.
void setIntervalYM(unsigned int paramIndex,const IntervalYM &x);
The first parameter is 1, the second is 2, . . . .
The parameter value.
Sets the maximum number of invocations that will be made for the DML statement. This must be called before any parameters are set on the prepared statement. The larger the iterations, the larger the numbers of parameters sent to the server in one round trip. However, a large number causes more memory to be reserved for all the parameters. Note that this is just the maximum limit. Actual number of iterations depends on the number of addIterations()
that are done.
void setMaxIterations(unsigned int maxIterations);
Maximum number of iterations allowed on this statement.
This method sets the maximum amount of data to be sent or received for the specified parameter. It only applies to character and binary data. If the maximum amount is exceeded, the excess data is discarded. This method can be very useful when working with a LONG
column. It can be used to truncate the LONG
column by reading or writing it into a string or Bytes
data type.
If the setString
or setBytes
method has been called to bind a value to an IN/OUT parameter of a pl/sql procedure, and the size of the OUT value is expected to be greater than the size of the IN value, then setMaxParamSize
should be called.
void setMaxParamSize(unsigned int paramIndex,unsigned int maxSize);
The first parameter is 1, the second is 2, . . . .
The new max parameter size limit (> 0) .
Set a parameter to SQL null. Note that you must specify the parameter's SQL type.
void setNull(unsigned int paramIndex,Type type);
The first parameter is 1, the second is 2, . . . .
SQL type code defined by Type
Set a parameter to a Number
value.
void setNumber(unsigned int paramIndex,const Number &x);
The first parameter is 1, the second is 2, . . . .
The parameter value.
Set the value of a parameter using an object; use the C++.lang equivalent objects for integral values. The OCCI specification specifies a standard mapping from C++ Object
types to SQL types. The given parameter C++ object will be converted to the corresponding SQL type before being sent to the database.
void setObject(unsigned int paramIndex,PObject * x);
The first parameter is 1, the second is 2, . . . .
The object containing the input parameter value.
Set the amount of memory that will be used internally by OCCI to store data fetched during each round trip to the server. A value of 0 means that the amount of data fetched during the round trip is constrained by the FetchRowCount
parameter. If both parameters are nonzero, the smaller of the two is used.
void setPrefetchMemorySize(unsigned int bytes);
Number of bytes to use for storing data fetched during each round trip to the server.
Set the number of rows that will be fetched internally by OCCI during each round trip to the server. A value of 0 means that the amount of data fetched during the round trip is constrained by the FetchMemorySize
parameter. If both parameters are nonzero, the smaller of the two is used. If both of these parameters are zero, row count internally defaults to 1 row and that is the value returned from the getFetchRowCount
method below.
void setPrefetchRowCount(unsigned int rowCount);
Number of rows to fetch for each round trip to the server.
Set a parameter to a RefAny
value.
void setRef(unsigned int paramIndex,RefAny &x);
The first parameter is 1, the second is 2, . . . .
The parameter value.
Set a Rowid
bytes array for a bind position.
void setRowid(unsigned int paramIndex,const Bytes &x);
The first parameter is 1, the second is 2, . . . .
The parameter value.
A new SQL string can be associated with a Statement
object by this call. Resources associated with the previous SQL statement are freed. In particular, a previously obtained result set is invalidated. If an empty sql string, "", was used when the Statement
was created, a setSQL
method with the proper SQL string must be done prior to execution.
void setSQL(const string &sql);
Any SQL statement.
Set a parameter to an string value.
void setString(unsigned int paramIndex,const string &x);
The first parameter is 1, the second is 2, . . . .
The parameter value.
Set a parameter to a Timestamp
value.
void setTimestamp(unsigned int paramIndex,const Timestamp &x);
The first parameter is 1, the second is 2, . . . .
The parameter value.
Set a parameter to a C++ unsigned int value.
void setUInt(unsigned int paramIndex,unsigned int x);
The first parameter is 1, the second is 2, . . . .
The parameter value.
This method sets a parameter to a vector of unsigned int.
There are variants of syntax:
void setVector(Statement *stmt,unsigned int paramIndex, vector<int> &vect, string sqltype);
void setVector(Statement *stmt,unsigned int paramIndex, vector<unsigned int> &vect, string sqltype);
void setVector(Statement *stmt,unsigned int paramIndex, vector<double> &vect, string sqltype);
void setVector(Statement *stmt,unsigned int paramIndex, vector<float> &vect, string sqltype);
void setVector(Statement *stmt,unsigned int paramIndex, vector<string> &vect, string sqltype);void setVector(Statement *stmt,unsigned int paramIndex, vector<RefAny> &vect, string sqltype);
void setVector(Statement *stmt,unsigned int paramIndex, vector<Blob> &vect, string sqltype);
void setVector(Statement *stmt,unsigned int paramIndex, vector<Clob> &vect, string sqltype);
void setVector(Statement *stmt,unsigned int paramIndex, vector<Bfile> &vect, string sqltype);
void setVector(Statement *stmt,unsigned int paramIndex, vector<Timestamp> &vect, string sqltype);
void setVector(Statement *stmt,unsigned int paramIndex, vector<IntervalDS> &vect, string sqltype);
void setVector(Statement *stmt,unsigned int paramIndex, vector<IntervalYM> &vect, string sqltype);
void setVector(Statement *stmt,unsigned int paramIndex, vector<Date> &vect, string sqltype);
void setVector(Statement *stmt,unsigned int paramIndex, vector<T *> &vect, string sqltype);
void setVector(Statement *stmt,unsigned int paramIndex, vector<Number> &vect, string sqltype);
void setVector(Statement *stmt,unsigned int paramIndex, vector<Ref<T>> &vect, string sqltype);
Returns the current status of the statement. Useful when there is streamed data to be written (or read). Other methods such as getCurrentStreamParam
and getCurrentIteration
can be called to find out the streamed parameter that needs to be written and the current iteration number for an iterative or array execute.
The status
method can be called repeatedly to find out the status of the execution. Returns one of following:
RESULT_SET_AVAILABLE
-- call getResultSet()
UPDATE_COUNT_AVAILABLE
-- call getUpdateCount()
NEEDS_STREAM_DATA
-- call getCurrentStream()
and getCurrentIteration()
, and write stream
STREAM_DATA_AVAILABLE
-- call getCurrentStream()
and getCurrentIteration()
, and read stream
PREPARED
UNPREPARED
Status status() const;
You use a Stream to read or write streamed data (usually LONG).
Stream() enum Status { READY_FOR_READ, READY_FOR_WRITE, INACTIVE };
Reads data from Stream
. The size parameter specifies the maximum number of byte characters to read. Returns the amount of data read from the Stream
object. -1 means end of data on the stream
int readBuffer(char *buffer,unsigned int size);
Pointer to data buffer; must be allocated and freed by caller
Size of the buffer.
This method reads the last buffer from the Stream
. It can also be called top discard unread data.
The size parameter specifies the maximum number of byte characters to read. Returns the amount of data read from the Stream
object. -1 means end of data on the stream.
int readLastBuffer(char *buffer,unsigned int size);
Pointer to data buffer; must be allocated and freed by caller.
Specifies the maximum number of bytes to be read.
Writes data from buffer to the stream. The amount of data written is determined by size.
void writeBuffer(char *buffer,unsigned int size);
Pointer to data buffer.
Number of char's in the buffer.
This method writes the last data buffer to the stream. It can also be called to write the last chunk of data.
The amount of data written is determined by size.
void writeLastBuffer(char *buffer,unsigned int size);
Pointer to data buffer.
Specifies the number of bytes to be written.
Returns the current status of the streams, which can be one of the following:
Status status() const;
This class conforms to the SQL92 TIMESTAMP and TIMESTAMPTZ types.
OCCI expects the SQL data type corresponding to the Timestamp
class to be of type TIMESTAMP WITH TIME ZONE.
Timestamp(const Environment *env,int year = 1, unsigned int month = 1, unsigned int day = 1, unsigned int hour = 0, unsigned int min = 0, unsigned int sec = 0, unsigned int fs = 0, int tzhour = 0,
Returns a null Timestamp
object. A null timestamp can be initialized by assignment or calling the fromText
method. Methods that can be called on null timestamp objects are setNull
, isNull and operator=()
.
Timestamp();
Assigns the values found in a
.
Timestamp(const Timestamp &src);
The following code example demonstrates that the default constructor creates a null value, and how you can assign a non null value to a timestamp and perform operations on it:
Environment *env = Environment::createEnvironment(); //create a null timestamp Timestamp ts; if(ts.isnull())cout << "\n ts is Null";//assign a non null value to ts Timestamp notNullTs(env, 2000, 8, 17, 12, 0, 0, 0, 5, 30); ts = notNullTs; //now all operations are valid on ts... int yr; unsigned int mth, day; ts.getDate(yr, mth, day);
The following code example demonstrates how to use the fromText
method to initialize a null timestamp:
Environment *env = Environment::createEnvironment(); Timestamp ts1; ts1.fromText("01:16:17.12 04/03/1825", "hh:mi:ssxff dd/mm/yyyy", "", env);
The following code example demonstrates how to get the timestamp column from a result set, check whether the timestamp is null, get the timestamp value in string format, and determine the difference between 2 timestamps:
Timestamp reft(env, 2001, 1, 1); ResultSet *rs=stmt->executeQuery("select order_date from orders where customer_id=1"); rs->next(); //retrieve the timestamp column from result set Timestamp ts=rs->getTimestamp(1); //check timestamp for null if(!ts.isNull()) {//get the timestamp value in string format string tsstr=ts.toText("dd/mm/yyyy hh:mi:ss [tzh:tzm]",0); if(reft<ts //compare timestamps {IntervalDS ds=reft.subDS(ts); //get difference between timestamps}}
If nlsParam
is specified, this will determine the nls parameters to be used for the conversion. If nlsParam
is not specified, the nls parameters are picked up from env
. If env
is null, the nls parameters are picked up from the environment associated with the instance, if any.
void fromText(const string ×tmpStr,const string &fmt, const string &nlsParam = "", const Environment *env = NULL);
Return the year, day, and month values of the Timestamp
.
void getDate(int &year,unsigned int &month, unsigned int &day) const;
Return the hour, minute, second, and fractional second (fs) values.
void getTime(unsigned int &hour,unsigned int &minute, unsigned int &second, unsigned int &fs) const;
Returns the time zone offset from GMT in hours and minutes.
void getTimeZoneOffset(int &hour,int &minute) const;
Returns a Timestamp
with the value of this + val
.
There are variants of syntax:
Timestamp intervalAdd(const IntervalDS& val) const;
Timestamp intervalAdd(const IntervalYM& val) const;
Returns a Timestamp
with the value of this - val
.
There are variants of syntax:
Timestamp intervalSub(const IntervalDS& val) const;
Timestamp intervalSub(const IntervalYM& val) const;
Returns true
if Timestamp
is null or false
otherwise.
bool isNull() const;
Assigns the values found in src
to the Timestamp
object.
Timestamp & operator=(const Timestamp &src);
Returns true
if a is the same as b
, false
otherwise. If either a
or b
is null then false is returned.
bool operator==(const Timestamp &a,const Timestamp &b
);
A timestamp.
Another timestamp.
This method compares the timestamps specified. If the timestamps are not equal then true is returned; otherwise, false is returned. If either timestamp is null then false is returned.
bool operator!=(const Timestamp &a,const Timestamp &b);
A timestamp.
Another timestamp.
Returns true
if a is after b
, false
otherwise. If either a
or b
is null then false is returned.
bool operator>(const Timestamp &a,const Timestamp &b
);
A timestamp.
Another timestamp.
This method compares the timestamps specified. If the first timestamp is greater than or equal to the second timestamp then true is returned; otherwise, false is returned. If either timestamp is null then false is returned.
bool operator>=(const Timestamp &a,const Timestamp &b);
A timestamp.
Another timestamp.
Returns true
if a
is before b
, false
otherwise. If either a
or b
is null then false is returned.
bool operator<(const Timestamp &a,const Timestamp &b
);
A timestamp.
Another timestamp.
This method compares the timestamps specified. If the first timestamp is less than or equal to the second timestamp then true is returned; otherwise, false is returned. If either timestamp is null then false is returned.
bool operator<=(const Timestamp &a,const Timestamp &b);
A timestamp.
Another timestamp.
Sets the year, month, day components contained for this timestamp
void setDate(int year,unsigned int month, unsigned int day);
void setNull();
Sets the day, hour, minute, second and fractional second components for this timestamp.
void setTime(unsigned int hour,unsigned int minute, unsigned int second, unsigned int fs);
Sets the hour and minute offset for timezone.
void setTimeZoneOffset(int hour,int minute);
Subtract dt from this (this - dt) and return the difference as a IntervalDS
.
IntervalDS subDS(const Timestamp& val) const;
Subtract dt from this (this - dt) and return the difference as a IntervalYM
.
IntervalYM subYM(const Timestamp& val) const;
If nlsParam
is specified, this will determine the nls parameters to be used for the conversion. If nlsParam
is not specified, the nls parameters are picked up from envp
. If envp
is null, the nls parameters are picked up from the environment associated with the instance, if any.
string toText(const string &fmt,unsigned int fsprec, const string &nlsParam = "") const;
|
Copyright © 1996-2001, Oracle Corporation. All Rights Reserved. |
|