IldRelation Class Reference

Instances of the class IldRelation represent the relations (tables or views) in a database. More...

#include <ildblink/ildrel.h>

Inheritance diagram for IldRelation:

Public Member Functions
virtual	~IldRelation ()
	This destructor is invoked when the current IldRelation object is destroyed. More...
short	getColIndex (const char *name) const
	Get a column index from its name. More...
const char *	getColName (IlUShort index) const
	Get the name of a column. More...
IlUInt	getColSize (IlUShort index) const
	Get the column value size. More...
const char *	getColSQLType (IlUShort index) const
	Get a column SQL type name. More...
IldColumnType	getColType (IlUShort index) const
	Get a column type. More...
IldColumn *	getColumn (const char *colName) const
	Get a column by name. More...
IldColumn *	getColumn (IlUShort index) const
	Get a column by index. More...
IlUShort	getCount () const
	Get the number of columns. More...
IldFKey **	getForeignKeys ()
	Get the foreign keys. More...
IldTableIndex **	getIndexes ()
	Get the indexes of the relation. More...
IldKey *	getPrimaryKey ()
	Search the database schema for the primary key of the table. More...
IldKey *	getSpecialColumns ()
	Search the database schema for special columns in the table. More...
IlBoolean	isColNullable (IlUShort index) const
	Tell if a column can be null. More...
Public Member Functions inherited from IldSchemaEntity
virtual	~IldSchemaEntity ()
	This virtual destructor is invoked when any instance of a subclass from IldSchemaEntity is being destroyed. More...
IldDbms *	getDbms () const
	Get the attached to connection object. More...
IldEntityType	getEntityType () const
	Get the type of the entity. More...
IlInt	getId () const
	get the identifier of the entity. More...
const char *	getName () const
	Get the name of the entity. More...
const char *	getOwner () const
	Get the owner of the entity. More...

Detailed Description

Instances of the class IldRelation represent the relations (tables or views) in a database.

Library: dbkernel

Most of the functional interface of this class consists of accessors to the characteristics of a relation. These characteristics are the name and owner of the relation, and the name, type, and size of the relation fields.

Note

When, in the documentation of some function, it is said errors may be raised, it is meant that the error will be reported to the connection this object is attached to. Thus, after calling the function, the application should check the status by calling: this->getDbms()->isErrorRaised().

As the result of an SQL query, a given field may become part of a tuple. Such a field has the same characteristics as the column of a tuple; that is, a name, a type, and a size. It has an additional property: whether or not it can contain null values. This property is referred to as the nullability of the field.

See Also

IldDbms, IldFKey, IldKey, IldRequest, IldSchemaEntity, IldTableIndex

Constructor & Destructor Documentation

virtual IldRelation::~IldRelation ( )

virtual

This destructor is invoked when the current IldRelation object is destroyed.

The destructor also updates the IldDbms object that the relation is attached to.

Member Function Documentation

short IldRelation::getColIndex

(

const char *

name

)

const

Get a column index from its name.

Parameters

name	The column name.

Returns

The index of the column whose name is name in the relation.

The name argument must not be null or empty.

This member function can raise the following error:

• ILD_BAD_COLUMN_NAME
• ILD_OUT_OF_RANGE

The error is raised on the session if the object has been attached, otherwise, the error is not raised.

In case of error, whether attached to a session or not, a value of 0 is returned if the column name was not given; a value of -1 if no column with such a name could be found.

const char* IldRelation::getColName

(

IlUShort

index

)

const

Get the name of a column.

Parameters

idnex

The column index.

Returns

The name of the column located at the position indicated by index in the current relation.

It returns a constant character string. Your application must not deallocate this string because DB Link takes care of destroying it with the current object.

This member function can raise the following error:

• ILD_OUT_OF_RANGE

The error is raised on the session if the object has been attached, otherwise, the error is not raised.

When the function raises the error, its return value is a null object.

IlUInt IldRelation::getColSize

(

IlUShort

index

)

const

Get the column value size.

Parameters

index

Teh column index.

Returns

The size in bytes of values that can be stored in the column located at the position indicated by index in the relation.

This information is useful when you are formatting the values in fields of character-string type.

This member function can raise the following error:

• ILD_OUT_OF_RANGE

The error is raised on the session if the object has been attached, otherwise, the error is not raised.

In case of error, the value 0 is returned.

const char* IldRelation::getColSQLType

(

IlUShort

index

)

const

Get a column SQL type name.

Parameters

index

The column index.

Returns

The native name of the SQL type for the column located at the position indicated by index in the relation.

This member function can raise the following error:

• ILD_OUT_OF_RANGE

The error is raised on the session if the object has been attached, otherwise, the error is not raised.

In case of error, whether attached to a session or not, a null pointer is returned.

IldColumnType IldRelation::getColType

(

IlUShort

index

)

const

Get a column type.

Parameters

index

The column index.

Returns

The type of the column located at the position indicated by index in the current relation.

The member function returns one of the enumerated values of IldColumnType.

This member function can raise the following error:

• ILD_OUT_OF_RANGE

The error is raised on the session if the object has been attached, otherwise, the error is not raised.

In case of error, whether attached to a session or not, a value of IldUnknwonType is returned.

IldColumn* IldRelation::getColumn

(

const char *

colName

)

const

Get a column by name.

Parameters

colName

The column name.

Returns

The object describing the column whose name is colName.

The argument colName must not be a null pointer or an empty string.

This member function can raise the following errors:

• ILD_BAD_COLUMN_NAME
• ILD_OUT_OF_RANGE

The error is raised on the session if the object has been attached, otherwise, the error is not raised.

In case of error, whether atached to a session or not, a null object is returned.

Note

Depending upon the connected to RDBMS, the column name may be case sensitive. As the comparison is case sensitive, the application should ensure the name is using the appropriate case. For example, Oracle column names are upper case by default except if the name was declared surrounded by quotes when the table was created or altered.

IldColumn* IldRelation::getColumn

(

IlUShort

index

)

const

Get a column by index.

Parameters

index

The column index.

Returns

The column object located at the position index.

This member function can raise the following error:

• ILD_BAD_COLUMN_INDEX

The error is raised on the session if the object has been attached, otherwise, the error is not raised.

If the position is not possible, that is it is bigger than the number of columns in the relation, a null object is returned.

IlUShort IldRelation::getCount

(

)

const

Get the number of columns.

Returns

The number of fields in the relation.

IldFKey** IldRelation::getForeignKeys

(

)

Get the foreign keys.

Returns

A null-terminated array of IldFKey objects.

If none exist, the function returns a null pointer. The application must not delete the array nor the objects in it.

The foreign key descriptors are not created when the IldRelation object is created, but rather when this function is called for the first time.

If an error is raised during the retrieval of keys, it is reported to the attached IldDbms object.

If the relation is not attached to a session, this function does nothing and returns a null object.

IldTableIndex** IldRelation::getIndexes

(

)

Get the indexes of the relation.

Returns

A null-terminated array of IldTableIndex objects.

If none exist, the function returns a null pointer. The application must not delete the array nor the objects in it.

The index descriptors are not created when the IldRelation object is created, but rather when this function is called for the first time.

If an error is raised during the retrieval of indexes, it is reported to the attached IldDbms object.

If the relation is not attached to a session, this function does nothing and returns a null object.

IldKey* IldRelation::getPrimaryKey

(

)

Search the database schema for the primary key of the table.

Returns

The primary key if found, null otherwise.

If there is a primary key, it is returned as an object of the class IldKey. If none exists, it returns a null pointer. The returned object must not be deallocated.

The primary key descriptor is not created when the IldRelation object is created, but rather when this function is called for the first time.

If an error is raised during key retrieval, it is reported to the attached IldDbms object. If the relation is not attached to a session, this function does nothing and returns a null object.

IldKey* IldRelation::getSpecialColumns

(

)

Search the database schema for special columns in the table.

Returns

An IldKey object.

Warning

The returned object must not be deallocated.

The special-column descriptor is not created when the IldRelation object is created, but rather when this function is called for the first time.

If an error is raised during key retrieval, it is reported to the attached IldDbms object.

If the relation is not attached to a session, this function does nothing and returns a null object.

IlBoolean IldRelation::isColNullable

(

IlUShort

index

)

const

Tell if a column can be null.

Parameters

index

The column index.

Returns

IlTrue if the column located at the position indicated by index in the relation can contain null values. Otherwise, it returns IlFalse.

This member function can raise the following error:

• ILD_OUT_OF_RANGE

The error is raised on the session if the object has been attached, otherwise, the error is not raised.

In case of error, the value IlFalse is returned.