tmudr::TupleInfo Class Reference

Common base class for parameter lists and row layouts. More...

#include <sqludr.h>

Inheritance diagram for tmudr::TupleInfo:

Public Member Functions
int	getNumColumns () const
int	getColNum (const char *colName) const
int	getColNum (const std::string &colName) const
const ColumnInfo &	getColumn (int colNum) const
const ColumnInfo &	getColumn (const std::string &colName) const
const TypeInfo &	getType (int colNum) const
TypeInfo::SQLTypeClassCode	getSQLTypeClass (int colNum) const
int	getInt (int colNum) const
int	getInt (const std::string &colName) const
long	getLong (int colNum) const
long	getLong (const std::string &colName) const
double	getDouble (int colNum) const
double	getDouble (const std::string &colName) const
std::string	getString (int colNum) const
std::string	getString (const std::string &colName) const
const char *	getRaw (int colNum, int &byteLen) const
time_t	getTime (int colNum) const
bool	isAvailable (int colNum) const
void	getDelimitedRow (std::string &row, char delim='\|', bool quote=false, char quoteSymbol= '"', int firstColumn = 0, int lastColumn = -1) const
bool	wasNull () const
void	setInt (int colNum, int val) const
void	setLong (int colNum, long val) const
void	setDouble (int colNum, double val) const
void	setString (int colNum, const char *val) const
void	setString (int colNum, const char *val, int stringLen) const
void	setString (int colNum, const std::string &val) const
void	setTime (int colNum, time_t val) const
const char *	setFromDelimitedRow (const char *row, char delim='\|', bool quote=false, char quoteSymbol= '"', int firstColumnToSet = 0, int lastColumnToSet = -1, int numDelimColsToSkip = 0) const
void	setNull (int colNum) const
ColumnInfo &	getColumn (int colNum)
ColumnInfo &	getColumn (const std::string &colName)
void	addColumn (const ColumnInfo &column)
void	addIntColumn (const char *colName, bool isNullable=false)
void	addLongColumn (const char *colName, bool isNullable=false)
void	addCharColumn (const char *colName, int length, bool isNullable=false, TypeInfo::SQLCharsetCode charset=TypeInfo::CHARSET_UTF8, TypeInfo::SQLCollationCode collation=TypeInfo::SYSTEM_COLLATION)
void	addVarCharColumn (const char *colName, int length, bool isNullable=false, TypeInfo::SQLCharsetCode charset=TypeInfo::CHARSET_UTF8, TypeInfo::SQLCollationCode collation=TypeInfo::SYSTEM_COLLATION)
void	addColumns (const std::vector< ColumnInfo * > &columns)
void	addColumnAt (const ColumnInfo &column, int position)
void	deleteColumn (int i)
void	deleteColumn (const std::string &name)
int	getRecordLength () const
void	print ()

Detailed Description

Common base class for parameter lists and row layouts.

Describes a list of scalars, which could be columns of a table or a parameter list

Member Function Documentation

void TupleInfo::addCharColumn	(	const char *	colName,
		int	length,
		bool	isNullable = `false`,
		TypeInfo::SQLCharsetCode	charset = `TypeInfo::CHARSET_UTF8`,
		TypeInfo::SQLCollationCode	collation = `TypeInfo::SYSTEM_COLLATION`
	)

Add a fixed character output column.

The new column is added at the end.

Only use this method from within the UDR::describeParamsAndColumns() method.

Parameters:

	colName	Name of the column to add. Use UPPER CASE letters, digits and underscore, otherwise you will need to use delimited column names with matching case in Trafodion.
	length	Length of the new character column. For single-byte and variable byte character sets, the length is specified in bytes. For UTF-8, this is equivalent to CHAR(length BYTES) in SQL. For UCS2, the length is in UCS2 16-bit characters.
	isNullable	true if the added column should be nullable, false if the added column should have the NOT NULL constraint.
	charset	Character set of the new column.
	collation	Collation of the new column.

Exceptions:

UDRException

void TupleInfo::addColumn ( const ColumnInfo & column )

Add a new column.

Only use this method from within the following method:

UDR::describeParamsAndColumns()

Parameters:

column

Info of the new column to add.

Exceptions:

UDRException

void TupleInfo::addColumnAt	(	const ColumnInfo &	column,
		int	position
	)

Add a new column at a specified position.

Only use this method from within the UDR::describeParamsAndColumns() method.

Parameters:

	column	ColumnInfo object describing the new column.
	position	Position/ordinal number of the new column. All existing columns with ordinal numbers greater or equal to position will be shifted by one.

Exceptions:

UDRException

void TupleInfo::addColumns ( const std::vector< ColumnInfo * > & columns )

Add multiple columns to the table-valued output.

Only use this method from within the UDR::describeParamsAndColumns() method.

Parameters:

columns

Vector of ColumnInfo objects describing the columns to add.

Exceptions:

UDRException

void TupleInfo::addIntColumn	(	const char *	colName,
		bool	isNullable = `false`
	)

Add an integer output column.

The new column is added at the end.

Only use this method from within the UDR::describeParamsAndColumns() method.

Parameters:

	colName	Name of the column to add. Use UPPER CASE letters, digits and underscore, otherwise you will need to use delimited column names with matching case in Trafodion.
	isNullable	true if the added column should be nullable, false if the added column should have the NOT NULL constraint.

Exceptions:

UDRException

void TupleInfo::addLongColumn	(	const char *	colName,
		bool	isNullable = `false`
	)

Add a long output column.

The new column is added at the end.

Only use this method from within the UDR::describeParamsAndColumns() method.

Parameters:

	colName	Name of the column to add. Use UPPER CASE letters, digits and underscore, otherwise you will need to use delimited column names with matching case in Trafodion.
	isNullable	true if the added column should be nullable, false if the added column should have the NOT NULL constraint.

Exceptions:

UDRException

void TupleInfo::addVarCharColumn	(	const char *	colName,
		int	length,
		bool	isNullable = `false`,
		TypeInfo::SQLCharsetCode	charset = `TypeInfo::CHARSET_UTF8`,
		TypeInfo::SQLCollationCode	collation = `TypeInfo::SYSTEM_COLLATION`
	)

Add a VARCHAR output column.

The new column is added at the end.

Only use this method from within the UDR::describeParamsAndColumns() method.

Parameters:

	colName	Name of the column to add. Use UPPER CASE letters, digits and underscore, otherwise you will need to use delimited column names with matching case in Trafodion.
	length	Length of the new character column. For single-byte and variable byte character sets, the length is specified in bytes. For UTF-8, this is equivalent to CHAR(length BYTES). For UCS2, the length is in UCS2 16-bit characters.
	isNullable	true if the added column should be nullable, false if the added column should have the NOT NULL constraint.
	charset	Character set of the new column.
	collation	Collation of the new column.

Exceptions:

UDRException

void TupleInfo::deleteColumn ( const std::string & name )

Delete a column with a specified column name.

The first column that matches the specified column name will be deleted.

Parameters:

name

Name of the column to be deleted.

Exceptions:

UDRException

void TupleInfo::deleteColumn ( int i )

Delete a column of the table-valued output.

Only use this method from within the UDR::describeParamsAndColumns() method.

Parameters:

i

Position/ordinal (0-based) of column to be deleted.

Exceptions:

UDRException

int TupleInfo::getColNum ( const std::string & colName ) const

Look up a column/parameter number by name.

Parameters:

colName

Name of an existing column.

Returns:: Column/parameter number.

Exceptions:

UDRException

int TupleInfo::getColNum ( const char * colName ) const

Look up a column/parameter number by name.

Parameters:

colName

Name of an existing column.

Returns:: Column/parameter number.

Exceptions:

UDRException

ColumnInfo & TupleInfo::getColumn ( const std::string & colName )

Get the non-const column info for a column identified by its name.

Parameters:

colName

Name of an existing column.

Returns:: Column info.

Exceptions:

UDRException

ColumnInfo & TupleInfo::getColumn ( int colNum )

Get the non-const column info for a column identified by its ordinal.

Parameters:

colNum

Column number.

Returns:: Column info.

Exceptions:

UDRException

const ColumnInfo & TupleInfo::getColumn ( const std::string & colName ) const

Get the column info for a column identified by its name.

Parameters:

colName

Name of an existing column.

Returns:: Column info.

Exceptions:

UDRException

const ColumnInfo & TupleInfo::getColumn ( int colNum ) const

Get the column info for a column identified by its ordinal.

Parameters:

colNum

Column number.

Returns:: Column info.

Exceptions:

UDRException

void TupleInfo::getDelimitedRow	(	std::string &	row,
		char	delim = `'\|'`,
		bool	quote = `false`,
		char	quoteSymbol = `'"'`,
		int	firstColumn = `0`,
		int	lastColumn = `-1`
	)			const

Get columns of a row as a delimited string.

This method is useful to interface with tools that take a delimited record format. It is also useful for printing rows (see UDRInvocationInfo::TRACE_ROWS).

Only use this method at runtime.

Note: This method may return a string that contains multiple character sets, if columns with different character sets are involved. Using this method with UCS-2 columns is not recommended.

Parameters:

	row	String reference in which the result delimited row will be returned.
	delim	US ASCII field delimiter to use.
	quote	Whether to quote character field values that contain the delimiter symbol or a quote symbol. Quote symbols will be duplicated to escape them.
	quoteSymbol	US ASCII quote character to use, if quote is true.
	firstColumn	First column to read.
	lastColumn	Last column to read (inclusive) or -1 to read until the last column in the row.

Exceptions:

UDRException

double TupleInfo::getDouble ( const std::string & colName ) const

Get double value of a column/parameter identified by name.

See also:: TupleInfo::getDouble(int colNum) const

Parameters:

colName

Name of an existing column.

Returns:: double value.

Exceptions:

UDRException

double TupleInfo::getDouble ( int colNum ) const

Get a double value of a column or parameter

This method is modeled after the JDBC interface.

Use this method at runtime. It can also be used for actual parameters that are available at compile time.

Parameters:

colNum

Column number.

Returns:: double value.

Exceptions:

UDRException

int TupleInfo::getInt ( const std::string & colName ) const

Get an integer value for a column identified by name.

See also:: TupleInfo::getInt(int) const

Parameters:

colName

Name of an existing column.

Returns:: Integer value. If the value was a NULL value, then 0 is returned. The wasNull() method can be used to determine whether a NULL value was returned.

Exceptions:

UDRException

int TupleInfo::getInt ( int colNum ) const

Get an integer value of a column or parameter

This method is modeled after the JDBC interface.

Use this method at runtime. It can also be used for actual parameters that are available at compile time.

Parameters:

colNum

Column number.

Returns:: Integer value. If the value was a NULL value, then 0 is returned. The wasNull() method can be used to determine whether a NULL value was returned.

Exceptions:

UDRException

long TupleInfo::getLong ( const std::string & colName ) const

Get a long value for a column identified by name.

See also:: TupleInfo::getLong(int) const

Parameters:

colName

Name of an existing column.

Returns:: long value.

Exceptions:

UDRException

long TupleInfo::getLong ( int colNum ) const

Get a long value of a column or parameter

This method is modeled after the JDBC interface.

Use this method at runtime. It can also be used for actual parameters that are available at compile time.

Parameters:

colNum

Column number.

Returns:: long value. If the value was a NULL value, then 0 is returned. The wasNull() method can be used to determine whether a NULL value was returned.

Exceptions:

UDRException

int TupleInfo::getNumColumns ( ) const

Get the number of columns or parameters.

Returns:: Number of columns/parameters.

const char * TupleInfo::getRaw	(	int	colNum,
		int &	byteLen
	)			const

Get a pointer to the raw data value of a column.

Using this method requires knowledge of the data layout for the different types used in UDRs. This method can be useful for performance optimizations, when converting longer string values to std::string is undesirable. Note that the pointer to the raw value is valid only until a new row is read or the existing row is emitted.

Use this method at runtime. It can also be used for actual parameters that are available at compile time.

Parameters:

	colNum	Column number.
	byteLen	Length, in bytes, of the value returned.

Returns:: Pointer to the raw column value in the row buffer.

Exceptions:

UDRException

int TupleInfo::getRecordLength ( ) const

Get the record length of a row.

This method returns the approximate record length of the tuple at compile time and the actual (non-compressed) record length at runtime. This might be useful for cost estimation, otherwise it can be ignored by UDF writers.

Returns:: Record length in bytes.

TypeInfo::SQLTypeClassCode TupleInfo::getSQLTypeClass ( int colNum ) const

Get the SQL type class.

Determine whether this is a numeric character, datetime or interval type.

Parameters:

colNum

Column number.

Returns:: SQL type class enum.

Exceptions:

UDRException

std::string TupleInfo::getString ( const std::string & colName ) const

Get a string value of a column or parameter identified by name.

This method is modeled after the JDBC interface.

Use this method at runtime. It cannot be used for actual parameters that are available at compile time, use getString(int colNum) instead, since actual parameters are not named.

Parameters:

colName

Name of an existing column.

Returns:: String value. If the value was a NULL value, an empty string is returned. The wasNull() method can be used to determine whether a NULL value was returned.

Exceptions:

UDRException

std::string TupleInfo::getString ( int colNum ) const

Get a string value of a column or parameter

This method is modeled after the JDBC interface.

Use this method at runtime. It can also be used for actual parameters that are available at compile time.

Parameters:

colNum

Column number.

Returns:: String value. If the value was a NULL value, an empty string is returned. The wasNull() method can be used to determine whether a NULL value was returned.

Exceptions:

UDRException

time_t TupleInfo::getTime ( int colNum ) const

Get a datetime or interval column value as time_t

This method can be used to convert column values with a datetime type or a day-second interval type to the POSIX type time_t. Note that this may result in the loss of fractional seconds.

Use this method at runtime. It can also be used for actual parameters that are available at compile time.

Parameters:

colNum

Column number.

Exceptions:

UDRException

const TypeInfo & TupleInfo::getType ( int colNum ) const

Get the type of a column.

Parameters:

colNum

Column number.

Returns:: Type of the column.

Exceptions:

UDRException

bool TupleInfo::isAvailable ( int colNum ) const

Check whether a parameter is available at compile-time.

Use this method to check in the compiler interfaces whether an actual parameter is a constant value that can be read at compile time. If this method returns true, the value can be accessed with the getInt(), getString() etc. methods.

Parameters:

colNum

Column number.

Returns:: true if the parameter value is available.

Exceptions:

UDRException

void TupleInfo::print ( )

Print the object, for use in debugging.

See also:: UDR::debugLoop(); UDRInvocationInfo::PRINT_INVOCATION_INFO_AT_RUN_TIME

Reimplemented in tmudr::TableInfo.

void TupleInfo::setDouble	(	int	colNum,
		double	val
	)			const

Set an output column to a specified double value.

Use this method at runtime.

Parameters:

	colNum	Index/ordinal of the column to set.
	val	The new double value for the column to set.

Exceptions:

UDRException

const char * TupleInfo::setFromDelimitedRow	(	const char *	row,
		char	delim = `'\|'`,
		bool	quote = `false`,
		char	quoteSymbol = `'"'`,
		int	firstColumnToSet = `0`,
		int	lastColumnToSet = `-1`,
		int	numDelimColsToSkip = `0`
	)			const

Set the result row from a string with delimited field values.

This method can be used to read delimited text files and conveniently produce a result table from them. For example, if the following string is passed in as row:

 skip1|'skip|2'|3|'delim|and''Quote'|5

This call:

 setFromDelimitedRow(
      row,  // row
      '|',  // delim
      true, // quote
      '\'', // quoteSymbol (single quote)
      10,   // firstColumnToSet
      11,   // lastColumnToSet
      2);   // numDelimColsToSkip

would set output column 10 to 3 and output column 11 to delim|and'Quote.

Note: The delimited row may need to contain strings of multiple character sets. Using this method with UCS2 columns is not recommended, since that might require special handling.

See also:: getDelimitedRow()

Parameters:

	row	A string with delimited field values to read.
	delim	Delimiter between field values. Use a US ASCII symbol as the delimiter.
	quote	true if the method should assume that text fields use quotes to quote special symbols like delimiters that are embedded within fields, and that quote symbols embedded in text fields will be doubled.
	quoteSymbol	US ASCII Quote symbol used to quote text. Meaningful only if quote is set to true.
	firstColumnToSet	First column in the output table to be set from the delimited row (0-based).
	lastColumnToSet	Last column in the output table to be set (inclusive) or -1 to indicate to set all remaining columns of the table.
	numDelimColsToSkip	Number of fields to skip in the delimited row before using the values to set output columns.

Returns:: Pointer to the first character after the text that has been consumed by this method.

Exceptions:

UDRException

void TupleInfo::setInt	(	int	colNum,
		int	val
	)			const

Set an output column to a specified integer value.

Use this method at runtime.

Parameters:

	colNum	Index/ordinal of the column to set.
	val	The new integer value for the column to set.

Exceptions:

UDRException

void TupleInfo::setLong	(	int	colNum,
		long	val
	)			const

Set an output column to a specified long value.

Use this method at runtime.

Parameters:

	colNum	Index/ordinal of the column to set.
	val	The new long value for the column to set.

Exceptions:

UDRException

void TupleInfo::setNull ( int colNum ) const

Set an output column to a NULL value.

Use this method at runtime.

Parameters:

colNum

Index/ordinal of the column to set to NULL.

Exceptions:

UDRException

void TupleInfo::setString	(	int	colNum,
		const std::string &	val
	)			const

Set an output column to a specified string value.

Use this method at runtime.

Parameters:

	colNum	Index/ordinal of the column to set.
	val	The new string value for the column to set.

Exceptions:

UDRException

void TupleInfo::setString	(	int	colNum,
		const char *	val,
		int	stringLen
	)			const

Set an output column to a specified string value.

Use this method at runtime.

Parameters:

	colNum	Index/ordinal of the column to set.
	val	The new string value for the column to set.
	stringLen	Length (in bytes) of the string value provided. The string may contain embedded NUL bytes.

Exceptions:

UDRException

void TupleInfo::setString	(	int	colNum,
		const char *	val
	)			const

Set an output column to a specified string value.

Use this method at runtime. The length of the string is determined by calling strlen().

Parameters:

	colNum	Index/ordinal of the column to set.
	val	The new string value for the column to set. The length of the string is determined by calling strlen.

Exceptions:

UDRException

void TupleInfo::setTime	(	int	colNum,
		time_t	val
	)			const

Set a datetime or interval output column to a value specified as time_t

This method cannot be used with year-month intervals or data types that are not datetime or interval types. It is not possible to set fractional seconds with this method.

Use this method at runtime.

Parameters:

	colNum	Index/ordinal of the column to set.
	val	The new time_t value for the column to set.

Exceptions:

UDRException

bool TupleInfo::wasNull ( ) const

Check whether the last value returned from a getInt() etc. method was NULL.

This method is modeled after the JDBC interface.

Returns:: true if the last value returned from a getInt(), getString() etc. method was a NULL value, false otherwise.

The documentation for this class was generated from the following files:

sqludr.h
sqludr.cpp

tmudr::TupleInfo Class Reference

Public Member Functions

Detailed Description

Member Function Documentation