Class: TRecordSourceHandle

Declaration: RecordSource.h

Taxonomy Categories:

Member Functions:

~TRecordSourceHandle
TRecordSourceHandle
operator=
GetRecordCount
GetRecordsRemaining
GetColumnCount
GetColumnTitle
GetColumnType
GetColumnTypeHint
GetColumnTypeHintOfType
GetColumnTypeOfHint
FetchRecord
GetField
IsRandomAccess
GetRecordPosition
SetRecordPosition
GetFieldOfRecord
GetColumnSize

Interface Category:

API.

Inherits From:

None.

Inherited By:

TSQLColumnCatalogHandle TSQLTableCatalogHandle

Purpose:

This concrete class is the counted pointer memory management surrogate for TRecordSource class. Clients access record sources using instances of this class.

Instantiation:

Always allocate on the stack.

Deriving Classes:

None.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TRecordSourceHandle::~TRecordSourceHandle

virtual ~ TRecordSourceHandle ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecordSourceHandle::TRecordSourceHandle

TRecordSourceHandle (TRecordSource & source)
TRecordSourceHandle (const TRecordSourceHandle & source)
TRecordSourceHandle ()

Interface Category:

API.

Purpose:

Downcast constructor.
Copy constructor.
Default constructor. Provides client with a handle to a null record source that throws an exception when its data access member functions are called.

Calling Context:

Call this function directly
Called to copy an object.
Called by the stream-in operators and any other function that needs to construct an uninitialized object.

Parameters:

TRecordSource & source -The master object.
const TRecordSourceHandle & source -The object to copy.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecordSourceHandle::operator=

TRecordSourceHandle & operator =(const TRecordSourceHandle & right)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TRecordSourceHandle & right -The object to copy.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecordSourceHandle::GetRecordCount

virtual ERecordSourceLength GetRecordCount (RecordCount & count) const

Interface Category:

API.

Purpose:

Returns the number of records in the record source if the returned value (ELength) is kFixed; otherwise, returns 0.

Calling Context:

Call this function directly.

Parameters:

RecordCount & count -On return, holds the number of records in the record source if the returned value is kFixed.

Return Value:

Returns kFixed if the record source has a prespecified fixed length; otherwise, returns 0.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecordSourceHandle::GetRecordsRemaining

virtual ERecordSourceLength GetRecordsRemaining (RecordCount & count) const

Interface Category:

API.

Purpose:

Returns the number of records remaining in the record source if the returned value (ELength) is kFixed; otherwise, returns 0.

Calling Context:

Call this function directly.

Parameters:

RecordCount & count -On return, holds the number of records remaining in the record source if the returned value is kFixed.

Return Value:

Returns kFixed if the record source has a prespecified fixed length; otherwise, returns 0.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecordSourceHandle::GetColumnCount

virtual ColumnCount GetColumnCount () const

Interface Category:

API.

Purpose:

Returns the number of columns in the record source.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The number of columns in the record source.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecordSourceHandle::GetColumnTitle

virtual void GetColumnTitle (ColumnPosition, TText &) const

Interface Category:

API.

Purpose:

Returns the title of the indicated column.

Calling Context:

Call this function directly.

Parameters:

ColumnPosition -Specifies the column.
TText & -On return, holds the column's title.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecordSourceHandle::GetColumnType

virtual const ColumnType & GetColumnType (ColumnPosition, ColumnType &) const

Interface Category:

API.

Purpose:

Returns the data type of fields in the indicated column. This is identical to the value returned by a TRecordFieldHandle::Name member function.

Calling Context:

Call this function directly.

Parameters:

ColumnPosition -Specifies the column.
ColumnType & -On return, holds the column type.

Return Value:

A const reference to the column type.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecordSourceHandle::GetColumnTypeHint

virtual EColumnTypeHint GetColumnTypeHint (ColumnPosition) const

Interface Category:

API.

Purpose:

Returns an enumerated column type hint. This type can be more convenient to work with than the column type returned by GetColumnType.

Calling Context:

Call this function directly.

Parameters:

ColumnPosition -Specifies the column.

Return Value:

A column type hint.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecordSourceHandle::GetColumnTypeHintOfType

static EColumnTypeHint GetColumnTypeHintOfType (ColumnType)

Interface Category:

API.

Purpose:

Returns an enumerated column type hint associated with the given column type.

Calling Context:

Call this function directly.

Parameters:

ColumnType -The type of column to return a hint for.

Return Value:

A column type hint.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecordSourceHandle::GetColumnTypeOfHint

static ColumnType GetColumnTypeOfHint (EColumnTypeHint)

Interface Category:

API.

Purpose:

Returns a column type associated with the given column type hint.

Calling Context:

Call this function directly.

Parameters:

EColumnTypeHint -A hint for the column type to return.

Return Value:

A column type.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecordSourceHandle::FetchRecord

virtual bool FetchRecord ()
virtual bool FetchRecord (TRecordHandle &)

Interface Category:

API.

Purpose:

Returns true if the next record can be fetched successfully from the source. Returns false at the end of the source.
Returns a record that the client can keep.

Calling Context:

Call this function directly.
Call this function directly.

Parameters:

Takes no parameters.
TRecordHandle & -On return, holds a copy of the fetched record.

Return Value:

Returns true if the record is fetched successfully from the source.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecordSourceHandle::GetField

virtual bool GetField (TRecordFieldHandle &, ColumnPosition) const
virtual bool GetField (unsigned char &, ColumnPosition) const
virtual bool GetField (short &, ColumnPosition) const
virtual bool GetField (long &, ColumnPosition) const
virtual bool GetField (double &, ColumnPosition) const
virtual bool GetField (TText &, ColumnPosition) const
virtual bool GetField (TTime &, ColumnPosition) const
virtual bool GetField (TSQLTime &, ColumnPosition) const
virtual bool GetField (TSQLDate &, ColumnPosition) const
virtual bool GetField (TSQLTimestamp &, ColumnPosition) const

Interface Category:

API.

Purpose:

Updates the client field handle of the specified field of the current record.
Fetches an unsigned char from the specified field of the current record.
Fetches a short from the specified field of the current record.
Fetches a long from the specified field of the current record.
Fetches a double from the specified field of the current record.
Fetches a TText from the specified field of the current record.
Fetches a TTime from the specified field of the current record.
Fetches a TSQLTime from the specified field of the current record.
Fetches a TSQLDate from the specified field of the current record.
Fetches a TSQLTimestamp from the specified field of the current record.

Calling Context:

Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.

Parameters:

TRecordFieldHandle & -On return, this handle is updated.
ColumnPosition -Specifies the field.
unsigned char & -On return, holds the field's value.
ColumnPosition -Specifies the field.
short & -On return, holds the field's value.
ColumnPosition -Specifies the field.
long & -On return, holds the field's value.
ColumnPosition -Specifies the field.
double & -On return, holds the field's value.
ColumnPosition -Specifies the field.
TText & -On return, holds the field's value.
ColumnPosition -Specifies the field.
TTime & -On return, holds the field's value.
ColumnPosition -Specifies the field.
TSQLTime & -On return, holds the field's value.
ColumnPosition -Specifies the field.
TSQLDate & -On return, holds the field's value.
ColumnPosition -Specifies the field.
TSQLTimestamp & -On return, holds the field's value.
ColumnPosition -Specifies the field.

Return Value:

Returns true if data exists. Returns false if no data exists in the indicated field of the current record.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecordSourceHandle::IsRandomAccess

virtual bool IsRandomAccess () const

Interface Category:

API.

Purpose:

Determines if the random access member functions are enabled for this record source.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the random access member functions are enabled.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecordSourceHandle::GetRecordPosition

virtual RecordPosition GetRecordPosition () const

Interface Category:

API.

Purpose:

Returns the record index of the current record in the record source.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The record index of the current record.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecordSourceHandle::SetRecordPosition

virtual bool SetRecordPosition (RecordPosition)

Interface Category:

API.

Purpose:

Positions the current record to the given record index.

Calling Context:

Call this function directly.

Parameters:

RecordPosition -The new record position.

Return Value:

Returns true if the record position can successfully be set, that is, if the specified record index exists.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecordSourceHandle::GetFieldOfRecord

virtual bool GetFieldOfRecord (TRecordFieldHandle &, ColumnPosition, RecordPosition) const
virtual bool GetFieldOfRecord (unsigned char &, ColumnPosition, RecordPosition) const
virtual bool GetFieldOfRecord (short &, ColumnPosition, RecordPosition) const
virtual bool GetFieldOfRecord (long &, ColumnPosition, RecordPosition) const
virtual bool GetFieldOfRecord (double &, ColumnPosition, RecordPosition) const
virtual bool GetFieldOfRecord (TText &, ColumnPosition, RecordPosition) const
virtual bool GetFieldOfRecord (TTime &, ColumnPosition, RecordPosition) const
virtual bool GetFieldOfRecord (TSQLTime &, ColumnPosition, RecordPosition) const
virtual bool GetFieldOfRecord (TSQLDate &, ColumnPosition, RecordPosition) const
virtual bool GetFieldOfRecord (TSQLTimestamp &, ColumnPosition, RecordPosition) const

Interface Category:

API.

Purpose:

Updates the client field handle of the specified field of the specified record.
Fetches an unsigned char from the specified field of the specified record.
Fetches a short from the specified field of the specified record.
Fetches a long from the specified field of the specified record.
Fetches a double from the specified field of the specified record.
Fetches a TText from the specified field of the specified record.
Fetches a TTime from the specified field of the specified record.
Fetches a TSQLTime from the specified field of the specified record.
Fetches a TSQLDate from the specified field of the specified record.
Fetches a TSQLTimestamp from the specified field of the specified record.

Calling Context:

Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.

Parameters:

TRecordFieldHandle & -On return, this handle is updated.
ColumnPosition -Specifies the field.
RecordPosition -Specifies the record.
unsigned char & -On return, holds the field's value.
ColumnPosition -Specifies the field.
RecordPosition -Specifies the record.
short & -On return, holds the field's value.
ColumnPosition -Specifies the field.
RecordPosition -Specifies the record.
long & -On return, holds the field's value.
ColumnPosition -Specifies the field.
RecordPosition -Specifies the record.
double & -On return, holds the field's value.
ColumnPosition -Specifies the field.
RecordPosition -Specifies the record.
TText & -On return, holds the field's value.
ColumnPosition -Specifies the field.
RecordPosition -Specifies the record.
TTime & -On return, holds the field's value.
ColumnPosition -Specifies the field.
RecordPosition -Specifies the record.
TSQLTime & -On return, holds the field's value.
ColumnPosition -Specifies the field.
RecordPosition -Specifies the record.
TSQLDate & -On return, holds the field's value.
ColumnPosition -Specifies the field.
RecordPosition -Specifies the record.
TSQLTimestamp & -On return, holds the field's value.
ColumnPosition -Specifies the field.
RecordPosition -Specifies the record.

Return Value:

Returns true if data exists. Returns false if no data exists in the indicated field of the specified record.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecordSourceHandle::GetColumnSize

virtual size_t GetColumnSize (ColumnPosition) const

Interface Category:

API.

Purpose:

Returns the column size of the largest data element in the given column. Might return 0 if the size is not known.

Calling Context:

Call this function directly.

Parameters:

ColumnPosition -Specifies the column.

Return Value:

The column size of the largest data element, or 0 if the size in unknown.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.