dtl

BoundIO and BoundIOs

Category: utilities	Component type: type

Description

A BoundIO is an object used to hold an association between a field in a query and a field in a user defined data object. The BoundIO class is held in a private member of the DBView template called the BoundIOs object which is an STL map<string, BoundIO> that holds a set of BoundIO objects that are mapped by SQL field name. As an end user, the four places you will encouter a BoundIO are when writing BCA , BPA, InsVal or SelVal functions.

Definition

Defined in the BoundIO.h header file.

Refinement of

None.

Associated types

NullField - a tag struct which indicates we want to set a field to null.

Example 1:

// Functor to bind SQL columns to a data object

class Example

{

  public:                                       // tablename.columnname:

	int exampleInt;                         // DB_EXAMPLE.INT_VALUE

	string exampleStr;                      // DB_EXAMPLE.STRING_VALUE

	double exampleDouble;                   // DB_EXAMPLE.DOUBLE_VALUE

	long exampleLong;                       // DB_EXAMPLE.EXAMPLE_LONG

	TIMESTAMP_STRUCT exampleDate;           // DB_EXAMPLE.EXAMPLE_DATE

};

class BCAExampleObj

{

public:

	void operator()(BoundIOs &boundIOs, Example &rowbuf)

    	{

	   boundIOs["INT_VALUE"] 	>> rowbuf.exampleInt;

	   boundIOs["STRING_VALUE"]	>> rowbuf.exampleStr;

	   boundIOs["DOUBLE_VALUE"]	>> rowbuf.exampleDouble;

	   boundIOs["EXAMPLE_LONG"]	>> rowbuf.exampleLong;

	   boundIOs["EXAMPLE_DATE"]	>> rowbuf.exampleDate;

	}

};

Example 2:

//BPA Functor to bind SQL parameters to a data object



// "Example" class to hold rows from our database table

class Example

{

  public:                                // tablename.columnname:

	int exampleInt;                 // DB_EXAMPLE.INT_VALUE

	string exampleStr;              // DB_EXAMPLE.STRING_VALUE

	double exampleDouble;           // DB_EXAMPLE.DOUBLE_VALUE

	long exampleLong;               // DB_EXAMPLE.EXAMPLE_LONG

	TIMESTAMP_STRUCT exampleDate;   // DB_EXAMPLE.EXAMPLE_DATE



	Example(int exInt, const string &exStr, double exDouble, long exLong,

		const TIMESTAMP_STRUCT &exDate) :

	   exampleInt(exInt), exampleStr(exStr), exampleDouble(exDouble), exampleLong(exLong),

	   exampleDate(exDate)

	{ }



};



// Create an association between table columns and fields in our object

class BCAExampleObj

{

public:

	void operator()(BoundIOs &cols, Example &rowbuf)

    	{

	   cols["INT_VALUE"] >> rowbuf.exampleInt;

	   cols["STRING_VALUE"] >> rowbuf.exampleStr;

	   cols["DOUBLE_VALUE"] >> rowbuf.exampleDouble;

	   cols["EXAMPLE_LONG"] >> rowbuf.exampleLong;

	   cols["EXAMPLE_DATE"] >> rowbuf.exampleDate;

	}

}



class ExampleParamObj

{

    public:

       	int lowIntValue;

	int highIntValue;

	string strValue;

	TIMESTAMP_STRUCT dateValue;

};



class BPAParamObj

{

public:

	void operator()(BoundIOs &boundIOs, ExampleParamObj &paramObj)

	{

	  boundIOs[0] << paramObj.lowIntValue;

	  boundIOs[1] << paramObj.highIntValue;

	  boundIOs[2] << paramObj.strValue;

	  boundIOs[3] << paramObj.dateValue;

	}



};



// read some Example objects from the database and return a vector of

// the results, use BPA to set join parameters

vector<Example> ReadData()

{

	vector<Example> results;



	// construct view

	

	DBView<Example, ExampleParamObj>

		view("DB_EXAMPLE", BCAExampleObj(),

		"WHERE INT_VALUE BETWEEN (?) AND (?) AND "

		"STRING_VALUE = (?) OR EXAMPLE_DATE < (?) ORDER BY EXAMPLE_LONG",

		BPAParamObj());



	// loop through query results and add them to our vector

	// in this loop, read_it.GetLastCount() records read from DB



	DBView<Example, ExampleParamObj>::select_iterator read_it = view.begin();



	// set parameter values for the WHERE clause in our SQL query

	read_it.Params().lowIntValue = 2;

	read_it.Params().highIntValue = 8;

	read_it.Params().strValue = "Example";

	

	TIMESTAMP_STRUCT paramDate = {2000, 1, 1, 0, 0, 0, 0};

	read_it.Params().dateValue = paramDate;



	for ( ; read_it != view.end();  read_it++)

	{

		cout << "Reading element #" << read_it.GetLastCount() << endl;

		results.push_back(*read_it);



		cout << "read_it->exampleInt = " << read_it->exampleInt << endl;

		cout << "read_it->exampleStr = " << read_it->exampleStr << endl;

		

	}

	

	return results;

}

Example 3:

//Default SelVal function to make sure fields in a row selected from the database are valid



// Default select validation behavior ... data is valid if and only if

// there are no columns which are null.

// If there are other checks you wish to make, put them in

// your own SelVal functor.

// You can also specialize this template if you wish to have different default behavior

// for your data class.

template<class DataObj> class DefaultSelValidate {

public:

bool operator()(BoundIOs &boundIOs, DataObj &rowbuf)

{

	for (BoundIOs::iterator b_it = boundIOs.begin();

				b_it != boundIOs.end(); b_it++)

	{

		BoundIO &boundIO = (*b_it).second;

		if (boundIO.IsColumn() && boundIO.IsNull())

			return false;  // found null column ... data is invalid

	}



	return true;	// no nulls found ... data is OK

}

};

Public base classes: BoundIO

None.

Public base classes: BoundIOs

map<string, BoundIO>

Notation:

Expression semantics: BoundIO

X a()

X a(constX &b)

X& operator=(const X&b)

bool IsColumn()

bool IsParam()

bool IsNull()

Expression semantics: BoundIOs

As per STL map but with the following modifications:

BoundIO &operator[](unsigned int paramNum)

BoundIO &operator[](const string &colName)

Notes

[1] Supported C++ types for binding to fields in a database:

Supported C++ data types and mappings (see ETI_Map::build() in bind_basics.cpp for details)

In addition to these basic types, you can also add custom bindings to DTL to support your own favorite types such as complex numbers or other kinds of structures that may span multiple database fields. DTL comes with some contributed user examples such as support for fields with an optional NULL value, or the direct mapping of enumerated values to database fields. For more on this see: Support for user defined types

[2] We recommend that you only use statically allocated fields in your BCA. The reason is that some of the logic in DBView & IndexedDBView uses field offsets within the class to compare fields for sorting and assignment. If you really want to use a dynamically allocated field, it can be done if the fields are allocated as a contiguous block, but it is a bit tricky. You can check out DynamicRowBCA in DynaDBView.h and the data_ptr() function that we define for the variant_row class in variant_row.h for an example of how we worked around this to accomodate dynamically sized rows. The result is not for the faint of heart.

See also

BPA, BCA, InsVal, SelVal, DBView, IndexedDBView

Copyright © 2002, Michael Gradman and Corwin Joy.

Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appears in all copies and that both that copyright notice and this permission notice appear in supporting documentation. Corwin Joy and Michael Gradman make no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.

This site written using the ORB.