RWDBColumn
Module: DB Interface Module Group: Database Classes
Does not inherit
- Local Index
- Synopsis
- Description
- About Precision and Scale
- Related Classes
- Public Enum
- Public Constructors
- Public Member Operator
- Public Member Functions
Local Index
Members
Synopsis
#include <rw/db/column.h> RWDBColumn c = myTable["columnName"];
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 RWDBColumns used to describe a database table, view, or stored procedure. When used in this way, RWDBColumn stores several pieces of information:
Name ----- the name of the column
Type ----- the type used to represent the data in the DB Interface Module
Native Type ----- the type specified by the database vendor
Storage Length ----- used mainly to store the length of string fields
Precision ----- the precision as defined by the database vendor
Scale ----- the scale as defined by the database vendor
Null Allowed ----- indicates if this column allows NULL values
Parameter Type ----- used in stored procedures to indicate if the parameter is for input, output, or both
Table ----- the table associated with the column
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.
Related Classes
RWDBColumn is commonly used to construct encapsulated SQL expressions, which 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, which are then used to construct instances of an RWDBAssignment and RWDBExpr, respectively.
For additional details, see RWDBExpr, RWDBAssignment, RWDBCriterion, RWDBSelector, RWDBInserter, RWDBUpdater, and RWDBDeleter.
Public Enum
enum ParamType { notAParameter, inParameter, outParameter,
inOutParameter };
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.
enum ParamType
{
notAParameter, // (the default)column does not
// represent a parameter or
// parameter type unknown
inParameter, // input parameter
outParameter, // output parameter
inOutParameter // input and output parameter
};
Public Constructors
RWDBColumn();
The default constructor 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(const RWDBColumn& column);
Copy constructor. The created RWDBColumn shares an implementation with column.
Public Member Operator
RWDBColumn& operator=(const RWDBColumn& column);
Assignment operator. Self shares an implementation with column. Returns a reference to self.
Public Member Functions
void 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 nonmultithreaded builds, this function evaluates to a no-op.
RWDBAssignment assign(const RWDBExpr& expression) const;
Returns an RWDBAssignment that represents an encapsulation of the SQL clause:
column = expression
where column refers to self. Just as the SQL SET clause is used only in the SQL UPDATE statement, RWDBAssignments are used only to build RWDBUpdaters.
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 RWCString& 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 RWDBExpr& expr) const; RWDBAssignment assign(const RWDBMBString& value) const; RWDBAssignment assign(const RWWString& value) const; RWDBAssignment assign(const wchar_t* value) const; RWDBAssignment assign(const RWDBValueManip manip) const; RWDBAssignment 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.
NOTE -- This function accepts Unicode strings. For more information, see the entry for RWBasicUString in the Essential Tools Module Reference Guide. For more information on internationalization, see Chapter 13 of the DB Interface Module User's Guide.
RWDBCriterion
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& clearTable();
Dissociates self from any table. Returns a reference to self.
RWDBColumn clone() const;
Returns a deep copy of self.
RWDBStatus::ErrorHandler errorHandler() const;
Returns the error handler attached to self.
RWDBCriterion 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)
we could write:
RWOrdered aCollection; RWDBCollectableExpr e1(RWDBExpr(1)), e2(RWDBExpr(2)); RWDBCollectableExpr e3(RWDBExpr(3)); aCollection.insert(&e1); aCollection.insert(&e2); aCollection.insert(&e3); RWDBExpr e(aCollection); table["col1"].in(e);
Alternatively, we could write:
table["col1"].in(RWDBExpr("(1,2,3)",false));
Note: the parameter false in the constructor for the RWDBExpr above is required in order to suppress quotation marks in the resultant SQL string. See RWDBExpr for more details.
bool isEquivalent(const RWDBColumn& column) const;
Returns a boolean value indicating whether or not self and column are equivalent. Columns are equivalent iff they have the same names and are associated with the same table.
RWDBCriterion isNull(void) 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 isValid() const;
Returns true if self's status is RWDBStatus::ok, otherwise returns false.
RWDBCriterion leftOuterJoin(const RWDBExpr& expression) 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 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%"
we would write:
table["col1"].like("%object%");
RWDBCriterion 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 name() const;
Returns the name of the column.
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 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& 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 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& nullAllowed(bool nullAllowed);
Changes the value of self's nullAllowed attribute to the value of allowNulls. Note that this does not change the definition of the column in the database. Returns a reference to self.
RWDBColumn::ParamType paramType() const;
Returns a value indicating the parameter type of the column.
RWDBColumn& paramType(RWDBColumn::ParamType type);
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 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& precision(int precision);
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 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 release() const;
Releases a previously acquired mutex. This function can be called from a const object. Note: in nonmultithreaded builds, this function evaluates to a no-op.
RWDBCriterion rightOuterJoin(const RWDBExpr& expression) const;
Returns an RWDBCriterion that represents an encapsulation of the right outer join SQL phrase. This function can be called from a const object. An RWDBCriterion is an encapsulation of an SQL WHERE clause.
int 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& scale(int scale);
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 setErrorHandler(RWDBStatus::ErrorHandler handler);
Installs handler as the error handler for self. By default, an RWDBColumn error handler is inherited from the object that produced the RWDBColumn; this method overrides the default. ErrorHandler is declared as a typedef within the scope of RWDBStatus:
typedef void (*ErrorHandler)(const RWDBStatus& status);
RWDBStatus status() const;
Returns the status of self.
long 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& 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 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& 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 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& type(RWDBValue::ValueType type);
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 Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.