SourcePro® API Reference Guide

 
List of all members | Public Types | Public Member Functions
RWDBColumn Class Reference

Represents a column within a table or schema, or a particular parameter of a stored procedure. More...

#include <rw/db/column.h>

Public Types

enum  ParamType { notAParameter, inParameter, outParameter, inOutParameter }
 

Public Member Functions

 RWDBColumn ()
 
 RWDBColumn (const RWDBColumn &column)
 
void acquire () const
 
RWDBAssignment assign (char value) const
 
RWDBAssignment assign (unsigned char value) const
 
RWDBAssignment assign (short int value) const
 
RWDBAssignment assign (unsigned short int value) const
 
RWDBAssignment assign (long int value) const
 
RWDBAssignment assign (unsigned long int value) const
 
RWDBAssignment assign (int value) const
 
RWDBAssignment assign (unsigned int value) const
 
RWDBAssignment assign (long long value) const
 
RWDBAssignment assign (unsigned long long value) const
 
RWDBAssignment assign (float value) const
 
RWDBAssignment assign (double value) const
 
RWDBAssignment assign (long double value) const
 
RWDBAssignment assign (const char *value) const
 
RWDBAssignment assign (const wchar_t *value) const
 
RWDBAssignment assign (const RWCString &value) const
 
RWDBAssignment assign (const RWDBMBString &value) const
 
RWDBAssignment assign (const RWWString &value) const
 
RWDBAssignment assign (const RWDate &value) const
 
RWDBAssignment assign (const RWTime &value) const
 
RWDBAssignment assign (const RWDateTime &value) const
 
RWDBAssignment assign (const RWDBDateTime &value) const
 
RWDBAssignment assign (const RWDBDuration &value) const
 
RWDBAssignment assign (const RWDecimalPortable &value) const
 
RWDBAssignment assign (const RWDBBlob &value) const
 
RWDBAssignment assign (const RWBasicUString &value) const
 
RWDBAssignment assign (RWDBValueManip value) const
 
RWDBAssignment assign (const RWDBExpr &expression) const
 
RWDBCriterion between (const RWDBExpr &expression1, const RWDBExpr &expression2) const
 
RWDBColumnclearTable ()
 
RWDBColumn clone () const
 
RWDBColumndefaultValue (const RWDBExpr &expr)
 
RWDBExpr defaultValue () const
 
RWDBStatus::ErrorHandler errorHandler () const
 
RWDBIdentityConstraint getIdentity () const
 
bool hasDefault () const
 
RWDBCriterion in (const RWDBExpr &expression) const
 
bool isEquivalent (const RWDBColumn &column) const
 
RWDBCriterion isNull () const
 
bool isValid () const
 
RWDBCriterion leftOuterJoin (const RWDBExpr &expr) const
 
RWDBCriterion like (const RWDBExpr &expression) const
 
RWDBCriterion matchUnique (const RWDBExpr &expression) const
 
RWCString name () const
 
RWDBColumnname (const RWCString &newName)
 
int nativeType () const
 
RWDBColumnnativeType (int newType)
 
bool nullAllowed () const
 
RWDBColumnnullAllowed (bool nullAllowed)
 
RWDBColumnoperator= (const RWDBColumn &column)
 
ParamType paramType () const
 
RWDBColumnparamType (RWDBColumn::ParamType newType)
 
int precision () const
 
RWDBColumnprecision (int newPrecision)
 
RWCString qualifiedName () const
 
void release () const
 
RWDBCriterion rightOuterJoin (const RWDBExpr &expr) const
 
int scale () const
 
RWDBColumnscale (int newScale)
 
void setErrorHandler (RWDBStatus::ErrorHandler handler)
 
RWDBColumnsetIdentity (const RWDBIdentityConstraint &constraint)
 
RWDBStatus status () const
 
long storageLength () const
 
RWDBColumnstorageLength (long newLength)
 
RWDBTable table () const
 
RWDBColumntable (const RWDBTable &table)
 
RWDBValue::ValueType type () const
 
RWDBColumntype (RWDBValue::ValueType newType)
 

Detailed Description

RWDBColumn provides a way to refer to a particular column of a table or schema, or to a particular parameter of a stored procedure. An application obtains instances of RWDBColumn by indexing into an RWDBTable or RWDBSchema.

RWDBColumn instances may be used in expressions (see RWDBExpr), which in turn are used to build up encapsulated SQL objects such as RWDBSelector.

RWDBColumn instances are also used in RWDBSchema. An RWDBSchema is a collection of RWDBColumn objects used to describe a database table, view, or stored procedure. When used in this way, RWDBColumn stores several pieces of information:

Note
The DB Interface Module does not obtain schema information until it is required. See RWDBTable::fetchSchema.

If no schema information has been obtained for the table containing a column, the column will contain default values. For Native Type, Storage Length, Precision, and Scale, this default value is RWDB_NO_TRAIT, and may be used in conditional expressions as follows:

RWDBTable myTable = myDbase.table("myTable");
...
...
RWDBColumn myColumn = myTable["someColumn"];
if( myColumn.scale() == RWDB_NO_TRAIT ) {
// do something;
}

RWDBColumn is designed around the Interface/Implementation paradigm. An RWDBColumn instance is an interface to a reference-counted implementation; copy constructors and assignment operators produce additional references to a shared implementation. Unlike many classes in the DB Interface Module, RWDBColumn implementations do not require database-specific variants.

About Precision and Scale

Precision and scale are used when defining numeric data types. Each database applies these specifications to data types in a slightly different manner. For example, Sybase applies precision and scale to decimal and numeric data types, while Oracle applies precision and scale to numeric data types only.

The precision of a column defines the total precision of the data type. For decimal data types, this translates into the total number of base ten digits. For floating point data types, this translates into binary digits or size.

The scale of a column defines the precision of the fractional part of the data type. For decimal data types, this translates into the total number of digits following the decimal point.

Note that precision and scale are often optional for a data type and that many databases apply default sizes when precision and scale are not provided.

For applications written with the DB Interface Module, precision and scale should always be specified if an application will create columns of a certain precision and scale. A DB Access Module can either disregard or use the necessary information in order to create a column of the correct data type. Typically, precision and scale should always be given for decimal columns.

Synopsis
#include <rw/db/column.h>
RWDBColumn c = myTable["columnName"];
See also

RWDBColumn is commonly used to construct encapsulated SQL expressions that can in turn become part of encapsulated SQL statements like RWDBSelector, RWDBInserter, RWDBDeleter, and RWDBUpdater. For example, to create an encapsulation of the SQL statement:

UPDATE myTable SET myColumn = 10 WHERE myKey < 100

we would write:

RWDBTable myTable = myDbase.table("myTable");
RWDBUpdater upd = myTable.updater();
upd << myTable["myColumn"].assign(10);
upd.where(myTable["myKey"] < 100);

Note that the index expressions myTable["myColumn"] and myTable["myKey"] result in the construction of RWDBColumn instances that are then used to construct instances of an RWDBAssignment and RWDBExpr, respectively.

For additional details, see RWDBExpr, RWDBAssignment, RWDBCriterion, RWDBSelector, RWDBInserter, RWDBUpdater, and RWDBDeleter.

Member Enumeration Documentation

RWDBColumn can be used to describe a parameter to a stored procedure. The ParamType enum describes the method of passing parameters between the application and the stored procedure. See RWDBStoredProc for more information.

Enumerator
notAParameter 

(the default) column does not represent a parameter or parameter type is unknown.

inParameter 

input parameter.

outParameter 

output parameter.

inOutParameter 

input and output parameter.

Constructor & Destructor Documentation

RWDBColumn::RWDBColumn ( )

Default constructor that creates a column whose status is RWDBStatus::notInitialized. This constructor is provided for convenience, for example, for declaring arrays of columns; valid columns are obtained by indexing into RWDBTable and RWDBSchema objects.

RWDBColumn::RWDBColumn ( const RWDBColumn column)

Copy constructor. The created RWDBColumn shares an implementation with column.

Member Function Documentation

void RWDBColumn::acquire ( ) const

Attempts to acquire the internal mutex lock. If the mutex is already locked by another thread, the function blocks until the mutex is released. This function can be called from a const object.

Note
In single-threaded builds, this function evaluates to a no-op.
RWDBAssignment RWDBColumn::assign ( char  value) const

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( unsigned char  value) const

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( short int  value) const

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( unsigned short int  value) const

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( long int  value) const

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( unsigned long int  value) const

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( int  value) const

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( unsigned int  value) const

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( long long  value) const

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( unsigned long long  value) const

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( float  value) const

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( double  value) const

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( long double  value) const

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( const char *  value) const

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( const wchar_t *  value) const

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( const RWCString value) const

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( const RWDBMBString value) const

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( const RWWString value) const

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( const RWDate value) const

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( const RWTime value) const
Deprecated:
As of SourcePro 11.1, use assign(const RWDateTime&) instead.

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( const RWDateTime value) const

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( const RWDBDateTime value) const
Deprecated:
As of SourcePro 11.1, use assign(const RWDateTime&) instead.

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( const RWDBDuration value) const

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( const RWDecimalPortable value) const

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( const RWDBBlob value) const

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( const RWBasicUString value) const

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( RWDBValueManip  value) const

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBAssignment RWDBColumn::assign ( const RWDBExpr expression) const

Returns an RWDBAssignment that represents an encapsulation of the SQL clause:

column = value

where column refers to self. Like the SQL SET clause, it is used only in the SQL UPDATE statement.

RWDBCriterion RWDBColumn::between ( const RWDBExpr expression1,
const RWDBExpr expression2 
) const

Returns an RWDBCriterion that represents an encapsulation of the SQL clause:

column BETWEEN expression1 AND expression2

where column refers to self. An RWDBCriterion is an encapsulation of an SQL WHERE clause.

RWDBColumn& RWDBColumn::clearTable ( )

Dissociates self from any table. Returns a reference to self.

RWDBColumn RWDBColumn::clone ( ) const

Returns a deep copy of self.

RWDBColumn& RWDBColumn::defaultValue ( const RWDBExpr expr)

Sets the default value for this column to expr. To unset a default value, pass an empty RWDBExpr created with the default constructor.

RWDBExpr RWDBColumn::defaultValue ( ) const

Returns the default value for this column. If there is no default, the returned RWDBExpr is not valid.

RWDBStatus::ErrorHandler RWDBColumn::errorHandler ( ) const

Returns the error handler attached to self.

RWDBIdentityConstraint RWDBColumn::getIdentity ( ) const

Returns a deep copy of self's RWDBIdentityConstraint.

bool RWDBColumn::hasDefault ( ) const

Returns true if this column has a default value.

RWDBCriterion RWDBColumn::in ( const RWDBExpr expression) const

Returns an RWDBCriterion that represents an encapsulation of the SQL phrase:

column IN expression

where column refers to self. An RWDBCriterion is an encapsulation of an SQL WHERE clause. For example, to produce the SQL clause:

col1 in (1, 2, 3)

you could write:

RWOrdered aCollection;
aCollection.insert(&e1);
aCollection.insert(&e2);
aCollection.insert(&e3);
RWDBExpr e(aCollection);
table["col1"].in(e);

Alternatively, you could write:

table["col1"].in(RWDBExpr("(1,2,3)",false));
Note
The parameter false in the constructor for the RWDBExpr in the example above is required in order to suppress quotation marks in the resultant SQL string. See RWDBExpr for more details.
bool RWDBColumn::isEquivalent ( const RWDBColumn column) const

Returns a boolean value indicating whether or not self and column are equivalent. Columns are equivalent if they have the same names and are associated with the same table.

RWDBCriterion RWDBColumn::isNull ( ) const

Returns an RWDBCriterion that represents an encapsulation of the SQL clause:

column IS NULL

where column refers to self. An RWDBCriterion is an encapsulation of an SQL WHERE clause.

bool RWDBColumn::isValid ( ) const

Returns true if self's status is RWDBStatus::ok, otherwise false.

RWDBCriterion RWDBColumn::leftOuterJoin ( const RWDBExpr expr) const

Returns an RWDBCriterion that represents an encapsulation of the LEFT OUTER JOIN SQL phrase for non-ANSI-compliant databases. See the entry for RWDBJoinExpr regarding ANSI-compliant joins. Also see the Access Module guides to determine which version of join is supported. An RWDBCriterion is an encapsulation of an SQL WHERE clause.

RWDBCriterion RWDBColumn::like ( const RWDBExpr expression) const

Returns an RWDBCriterion that represents an encapsulation of the SQL clause:

column LIKE expression

where column refers to self. For example, to produce the SQL clause:

col1 LIKE "%object%"

you would write:

table["col1"].like("%object%");
RWDBCriterion RWDBColumn::matchUnique ( const RWDBExpr expression) const

Returns an RWDBCriterion that represents an encapsulation of the SQL clause:

column MATCH UNIQUE expression

where column refers to self. An RWDBCriterion is an encapsulation of an SQL WHERE clause.

RWCString RWDBColumn::name ( ) const

Returns the name of the column.

RWDBColumn& RWDBColumn::name ( const RWCString newName)

Changes the name of this column to newName. Note that this does not change the definition of the column in the database. Returns a reference to self.

int RWDBColumn::nativeType ( ) const

Returns a value indicating the data type of the column as specified by the database vendor, or RWDB_NO_TRAIT if this information is not available. The meaning of the value returned depends on the database vendor's definitions.

RWDBColumn& RWDBColumn::nativeType ( int  newType)

Changes the nativeType attribute of self to newType. Note that this does not change the definition of the column in the database. Returns a reference to self.

bool RWDBColumn::nullAllowed ( ) const

Returns true if the database reports that a null value is allowed in this column, or if no schema information has been obtained. Otherwise returns false.

RWDBColumn& RWDBColumn::nullAllowed ( bool  nullAllowed)

Changes the value of self's nullAllowed attribute to the value of nullAllowed. Note that this does not change the definition of the column in the database. Returns a reference to self.

RWDBColumn& RWDBColumn::operator= ( const RWDBColumn column)

Assignment operator. Self shares an implementation with column. Returns a reference to self.

ParamType RWDBColumn::paramType ( ) const

Returns a value indicating the parameter type of the column.

RWDBColumn& RWDBColumn::paramType ( RWDBColumn::ParamType  newType)

Changes the paramType attribute of self to newType. Note that this does not change the definition of the parameter in the database. Returns a reference to self.

int RWDBColumn::precision ( ) const

Returns the precision of the column as reported by the database. If not applicable to this column, or if no schema information has been obtained, returns RWDB_NO_TRAIT.

RWDBColumn& RWDBColumn::precision ( int  newPrecision)

Changes the precision attribute of self to newPrecision. Note that this does not change the definition of the column in the database. Returns a reference to self.

RWCString RWDBColumn::qualifiedName ( ) const

Returns the name of the column qualified with the tag of the RWDBTable to which the column is associated. For example:

RWDBColumn col1 = table["col1"];
cout << col1.qualifiedName();

would produce output something like t123.col1. If self is not associated with any table, an unqualified name is returned.

void RWDBColumn::release ( ) const

Releases a previously acquired mutex. This function can be called from a const object.

Note
In single-threaded builds, this function evaluates to a no-op.
RWDBCriterion RWDBColumn::rightOuterJoin ( const RWDBExpr expr) const

Returns an RWDBCriterion that represents an encapsulation of the RIGHT OUTER JOIN SQL phrase for non-ANSI-compliant databases. See the entry for RWDBJoinExpr regarding ANSI-compliant joins. Also see the Access Module guides to determine which version of join is supported. This function can be called from a const object. An RWDBCriterion is an encapsulation of an SQL WHERE clause.

int RWDBColumn::scale ( ) const

Returns the scale of the column as reported by the database. If not applicable to this column, or if no schema information has been obtained, this routine returns RWDB_NO_TRAIT.

RWDBColumn& RWDBColumn::scale ( int  newScale)

Changes the scale attribute of self to newScale. Note that this does not change the definition of the column in the database. Returns a reference to self.

void RWDBColumn::setErrorHandler ( RWDBStatus::ErrorHandler  handler)

Installs handler as the error handler for self. By default, an RWDBStatus::ErrorHandler is inherited from the object that produced self; this method overrides the default.

RWDBColumn& RWDBColumn::setIdentity ( const RWDBIdentityConstraint constraint)

Sets self's identity constraint to a deep copy of constraint.

RWDBStatus RWDBColumn::status ( ) const

Returns the status of self.

long RWDBColumn::storageLength ( ) const

Returns the length of the column as reported by the database. This is often used to obtain the maximum string length. If no schema information has been obtained, returns RWDB_NO_TRAIT.

RWDBColumn& RWDBColumn::storageLength ( long  newLength)

Changes the storageLength attribute of self to newLength. Note that this does not change the definition of the column in the database. Returns a reference to self.

RWDBTable RWDBColumn::table ( ) const

Returns the table with which self is associated, or a table whose status is RWDBStatus::notInitialized if self is not associated with a table.

RWDBColumn& RWDBColumn::table ( const RWDBTable table)

Changes the table attribute of self to table, thus associating the column with table. Returns a reference to self.

RWDBValue::ValueType RWDBColumn::type ( ) const

Returns the data type used by the DB Interface Module to store this column's data; see RWDBValue for a list of valid types. If the type is not yet known, returns RWDBValue::NoType.

RWDBColumn& RWDBColumn::type ( RWDBValue::ValueType  newType)

Changes the data type attribute of self to newType. Note that this does not change the definition of the column in the database. Returns a reference to self.

Copyright © 2023 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved.