User-Defined Methods

By default, Data Access Builder generates methods that you can use in a C++ application to access your database. However, you may want to add your own methods (user-defined methods) to the generated classes. There are several ways for you to add these methods.

Note: These methods will be generated as static methods if they do not access any of the class' attributes.

The three types of user-defined methods are:

The following sections describe each of these types of user-defined methods in detail.

Customized SQL Statement
Suppose you want to add a method to find the average salary of all the employees. Data Access Builder lets you add this method to the mapping by selecting Methods from the mapping icon's popup menu. When you are adding the method, you will be asked to enter an SQL statement to define what the method does, for example:

SELECT AVG(SALARY) FROM EMPLOYEE

You then give a name to the method, for example, findAvgSalary, and describe the returned value (for example, its data type is float). When the code is generated, findAvgSalary is coded as a method in the Employee class.

This process of entering an SQL statement to specify the user-defined method is called User-Defined Methods with Customized SQL Statement. You will see this terminology used in the Data Access Builder user interface.

SQL Predicate
The Data Access Builder, by default, generates a select method in the <class>Manager class. The select method lets you retrieve a collection of rows from the database into memory, based on an SQL predicate passed in at run time. For example, if you want to work with all the department E11 employees from a table mapped to the object Employee, you can call the following method:

EmployeeManager theEmpMgr;
theEmpMgr.select("WORKDEPT = 'E11'");  //"WHERE" is automatically 
                                       //appended for select statements

If you know you are going to run this select method for department E11 frequently, you can add a user-defined method called DeptE11 which contains the SQL predicate, WHERE WORKDEPT = 'E11'. As a result, two methods, selectDeptE11 and openDeptE11, will be added to EmployeeManager class when code is generated. If you have specified a data ID for the table, two similar methods are also added to EmployeeDataIdManager class. Because the SQL predicate always returns a result set, this type method is only generated into the Manager classes (for example, EmployeeManager class and EmployeeDataIdManager class). Data Access Builder lets you add this method to the mapping by selecting Manager Methods from the mapping icon's popup menu. When you are adding the method, you will be asked to enter an SQL predicate, for example:

WHERE WORKDEPT = 'E11'

You give a name to this method, for example, DeptE11, and selectDeptE11, and openDeptE11 will be generated in EmployeeManager class and EmployeeDataIdManager class (if it exists). You can then use the methods from the generated class as follows:

theEmpMgr.selectDeptE11(const char* theSqlSuffix);

The SQL suffix parameter is an optional additional SQL statement that may be passed in at run time. For example, you may want to pass in "ORDER BY LASTNAME" to specify how the returned result set will be ordered.

You can also define methods that have variable values for parameters that are specified at run time. For example the SQL predicate for a method called AnyDept may be entered as:

WORKDEPT = ? 

In this case the following methods are generated:

selectDeptE11(const IString& deptno, const char* theSqlSuffix=0) 
openDeptE11(const IString& deptno, const char* theSqlSuffix=0)

This process of entering an SQL predicate to specify your method is called User-Defined Methods with SQL Predicate. You will see this terminology used in the Data Access Builder user interface.

Stored Procedure Call
You can also add a method that calls a database stored procedure. Stored procedures are procedures that operate on the database and are stored on the server of a remote database. When the stored procedure call method returns a single row or if it is a function call, you would add it to the <class> class. For example, if the stored procedure returns a single database row for the employee with the longest length of service, this stored procedure call method should be added to Employee persistent object class. Data Access Builder lets you add the method to the mapping by selecting Methods from the mapping icon's popup menu. When code is generated, your method is in Employee persistent object class.

However, if the stored procedure call returns a result set and you want to handle all the rows in the result set, you would add the method to the <class>Manager class. For example, if the stored procedure returns all employees eligible for retirement, you would add the method that calls it to EmployeeManager class. If you have specified a data ID, the method is also added to EmployeeDataIdManager class. Data Access Builder lets you add this method to the mapping by selecting Manager Methods from the mapping icon's popup menu. Two methods are generated, open<methodname> and select<methodname>, in both the EmployeeManager class and (if it exists) the EmployeeDataIdManager class.

Before you add the stored procedure call method, Data Access Builder must be told what the definition of the stored procedure is. Data Access Builder can connect to the database and retrieve definitions of its registered stored procedures. If a database connection is not available or if a stored procedure is not registered, you can define the stored procedure and its parameters to Data Access Builder manually. Of course in this situation, you are responsible for the correctness of the defined stored procedure. Once the stored procedure signature becomes known to Data Access Builder, you enter a name for the stored procedure call method, for example, FindRetireeCandidates, and map its parameters.

These methods that you have created are referred to as Stored Procedure Call User-Defined Methods. You will see this terminology used in the Data Access Builder user interface.

User-Defined Methods in Generated Classes
In summary, you can add user-defined methods in the generated classes as follows:

Class User-Defined Methods that You can Add
<class> Customized SQL Statement

Stored Procedure Call (returning a row or acting as a function call)

<class>DataId Not Applicable
<class>Manager

Two methods are generated: select<methodname> and open<methodname>

Stored Procedure Call (returning a result set)

SQL Predicate

<class>DataIdManager

Two methods are generated: select<methodname> and open<methodname>

Stored Procedure Call (returning a result set)

SQL Predicate

Other classes Not applicable


Data Access Builder Workflow
Keyless Table Support and Data Identifier


Add User-Defined Methods
Define Stored Procedures
Modify User-Defined Methods
Copy User-Defined Methods
Delete User-Defined Methods


Data Access Class Library and Generated Class Reference
Support for Non-Nullable Columns with Default Values
Sample: Create and Use a User-Defined Method With SQL Predicate
Sample: Create and Use a User-Defined Method With Customized SQL Statement
Sample: Create and Use a Stored Procedure Call on a Persistent Object