dtl

BCA


Category: functors	Component type: concept

Description

A BCA is a function object (this can be a wrapped function pointer if you use cb_ptr_fun()) that is called to create an association between the columns in a SQL view [1] and the fields in a user defined data object that is used to represent individual rows from the view. Supported C++ types for binding to the fields in a database are shown in the BoundIO documentation.

Each possible form of information flow between boundIO and DataObj/ParamObj corresponds to whether the parameter passed in to the query is an input, output, or input/output parameter. The user must be able to define the direction of information flow for parameters in cases such as stored procedure calls. The new binding syntax DTL provides shows the flow of information very clearly:

Expressions	Parameter Type	Description
boundIOs[colName] << dataObj.member boundIOs[paramNum] << paramObj.member	INPUT	The DataObj/ParamObj member supplies data needed by the SQL query.
boundIOs[colName] >> dataObj.member boundIOs[paramNum] >> paramObj.member	OUTPUT	The DataObj/ParamObj member receives data back from the SQL query.
boundIOs[colName] == dataObj.member boundIOs[paramNum] == paramObj.member	INPUT/OUTPUT	The DataObj/ParamObj member both supplies data to and receives back data from the SQL query.

You should always use this new syntax with any BCA's and BPA's you define. To maintain backwards compatibility with BCA's and BPA's for select_iterator's, insert_iterator's, delete_iterator's, and update_iterator's, the use of "boundIOs[colName] == dataObj.member" and "boundIOs[paramNum] == paramObj.member" is still legal. The direction of information flow can be inferred from the type of iterator used in those cases. However, the directional syntax is mandatory for sql_iterators as no information flow semantics can be inferred from a general SQL query. Examples in this documentation may use both forms of syntax where legal.

Refinement of

None.

Associated types

BoundIOs.

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;
	}
};

Notation

`X`	A type that is a model of BCA
`a`	Object of type `X`

Expression semantics

Name	Expression	Semantics	Postcondition
Default constructor	X a()	Construct the function object.
Copy constructor	X a(constX &b)	Copy construct the BCA.
Assignment operator	X& operator=(const X&b)	Assignment copy
Bind columns operator	void operator()(BoundIOs &boundIOs, DataObj &rowbuf)	This operator takes a BoundIOs object and a reference to a rowbuf holding a user defined data object of type DataObj. The job of the bind columns operator is to create an association between fields in a SQL view and fields in a user defined data object to hold rows from the view. This association is usually created by invoking the following cantrip: boundIOs["SQL Field Name"] == rowbuf.FieldName for each field to be included in the SQL query. For details on this syntax see BoundIOs. The fields to be bound must be statically allocated members of the DataObj (there are some exceptions - see BoundIOs for details). At the end of the operation, all fields to be bound in the SQL query must be in the BoundIOs container. When operator() is called, the BoundIOs container starts out empty.	BoundIOs contains a complete list of fields to be bound to the DataObj.

Notes

[1] We use the term 'view' here to indicate two common cases. The first case is when we are referring to fields from a single table. In this case, we can usually either select, insert, update or delete records. The second case is when we are selecting multiple fields from multiple tables as joined together with a WHERE clause. In the second case, we can usually only select records.

BCA