Class: TRecordSource

Declaration: RecordSource.h

Taxonomy Categories:

Member Functions:

TRecordSource
~TRecordSource
GetRecordCount
GetRecordsRemaining
GetColumnCount
GetColumnTitle
GetColumnType
GetColumnTypeHint
GetColumnSize
GetField
FetchRecord
IsRandomAccess
GetRecordPosition
SetRecordPosition
GetFieldOfRecord

Interface Category:

API.

Inherits From:

MReferenceCounted

Inherited By:

None.

Purpose:

The TRecordSource is an abstract base class that defines the member functions that record source providers must define. The TRecordSource class is associated with a stateless memory management surrogate class, TRecordSourceHandle. Record source instances cannot be assigned or copied to one another.

Instantiation:

Abstract class; do not allocate. Clients access record sources using instances of TRecordSourceHandle.

Deriving Classes:

Record source providers will need to derive from this class.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TRecordSource::TRecordSource

TRecordSource ()

Interface Category:

API.

Purpose:

Default constructor.

Calling Context:

Called by the stream-in operators and any other function that needs to construct an uninitialized 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: TRecordSource::~TRecordSource

virtual ~ TRecordSource ()

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: TRecordSource::GetRecordCount

virtual ERecordSourceLength GetRecordCount (RecordCount &) 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 & -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: TRecordSource::GetRecordsRemaining

virtual ERecordSourceLength GetRecordsRemaining (RecordCount &) 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 & -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: TRecordSource::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: TRecordSource::GetColumnTitle

virtual const TText & 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:

A const reference to the column's title.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecordSource::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: TRecordSource::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: TRecordSource::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.

Member Function: TRecordSource::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: TRecordSource::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: TRecordSource::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: TRecordSource::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: TRecordSource::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: TRecordSource::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.

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