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

◆ ~IldRelation()

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

◆ getColIndex()

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.

◆ getColName()

const char* IldRelation::getColName ( IlUShort index ) const

Get the name of a column.

Parameters

index 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.

◆ getColSize()

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.

◆ getColSQLType()

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.

◆ getColType()

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.

◆ getColumn() [1/2]

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.

◆ getColumn() [2/2]

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.

◆ getCount()

IlUShort IldRelation::getCount ( ) const

Get the number of columns.

Returns: The number of fields in the relation.

◆ getForeignKeys()

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.

◆ getIndexes()

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.

◆ getPrimaryKey()

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.

◆ getSpecialColumns()

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.

◆ isColNullable()

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.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~IldRelation()

Member Function Documentation

◆ getColIndex()

◆ getColName()

◆ getColSize()

◆ getColSQLType()

◆ getColType()

◆ getColumn() [1/2]

◆ getColumn() [2/2]

◆ getCount()

◆ getForeignKeys()

◆ getIndexes()

◆ getPrimaryKey()

◆ getSpecialColumns()

◆ isColNullable()