File modification

There are two files you may want to modify to customize your Business Logic Tier (BLT) Component: the constructor and the process() method.

Modifying the Constructor

The constructor of the <name>Processor class can be modified to initialize any member variables that you create. It is also where you must initialize the component’s parameters. In order to modify the constructor, you must create a list of its parameters.

The constructor for the <name>Processor component is where you generate the parameter list for the component. This list determines how many parameters there are, which of them are input or output, and what type each parameter is. These parameters are validated by the BLTComponent class. Parameter information is also made available to the client in XML form. The XML shows details for each parameter as well as a general usage string.

Generate a parameter list by creating a BLTParameterList object and adding BLTParameter objects to it. You can override the usage string by setting the BLTParameterList::UsageText property. Save the parameter list in the component by setting the this.Parameters property.

Modifying the Process() Method

Reading Input Parameters is a fundamental step in changing the process method. Input parameters are passed by the this.Parameters property that you set in the constructor. Each BLTParameter object in the list contains a parameter value. Retrieve the parameters with code like this (C# version):

string szCity = this.Parameters.Item(0).Value.ToString();int iSomeNumber = (int) this.Parameters.Item(1).Value;

Parameters are expected to appear in the same order in which they were added in the constructor. It is also important to be mindful of how you write output parameters. Output parameters are designated as such with the IsOutput property:

if(this.Parameters.Item(0).IsOutput == true) then{…}

Output parameters are set by modifying the Value property of the BLTParameter object in the Parameters list:

this.Parameters.Item(0).Value = "test";

this.Parameters.Item(1).Value= 1;

You can use the built-in properties, to modify your process method in even more detail. The BLTProcessor class, from which the <name>Processor class is derived, contains other useful properties. These are listed in the following table.

 

Optional properties for Process method modification 

 

Note: Use the Object Browser to examine the built in properties for the BLT.

Returning rows to the client helps you verify that your changes to the Process method have worked. The this.AddResultSet method is used to return rows of data to the client. This method takes a DataTable object as a parameter. The DataTable class is an ADO.NET datatype available under the System.Data namespace.

To return rows to the client, create a DataTable object and use the methods provided to add columns and rows. Then use the this.AddResultSet method to save the recordset for returning to the client. Multiple DataTables may be returned.

DataTable tabularResult = new DataTable ("DataTable1");

tabularResult.Columns.Add ("StringColumn", type of (String));

tabularResult.Columns.Add ("IntColumn", type of (int));

DataRow row = tabularResult.NewRow();

row ["StringColumn"] = "aString";

row ["IntColumn"] =1;

tabularResult.Rows.Add(row);

this.ResultSet (tabularResult);

You may also want to return errors to the client to edit your changes to the Process method. Errors can be returned to the client by throwing a BLTException or System.Exception exception. Errors should be divided into two types:

Unexpected errors (OS-related, memory access, crashes, etc.). Throw a System.Exception exception to signify these errors.

Expected errors (RealTime dberr codes, errors caused by the client, database locks being held, etc.). The built in BLTException class error code is used to signify these errors. Throw a BLTException exception to signify these errors.

Expected errors are not serious and do not affect the operation of the system. However, they should generally be communicated to the client via a descriptive message, so that the client can show the message to the Administrator/Controller.

Example 1: Sending an expected error to the client

BLTException bltexcept = new BLTException("User error");throw(bltexcept);

Unexpected errors require the intervention of highly technical personnel, and usually have a negative impact on system operations. As such, they should be logged in the oasErrLog.log file. A message indicating that the Administrator/Controller call technical support (or some other appropriate message) should be sent to the client.

The <name>Component class already traps all unexpected errors and logs them to the oasErrLog.log file, so you usually don’t need to worry about them. However, in cases where you do need to trap these kinds of errors, the following example should help:

Example 2: Trapping and logging an unexpected error

try

{

// … processing code ….

}

catch(System.Exception except)

{

OASySDNA.Common.DNALog.DumpNonFatalExceptionTocobjLog(except);

System.Exception newexcept = new System.Exception("Internal error.Consult the oasErrLog.log file for details.");

throw(newexcept);

}