Chapter 3: Building Production Objects

Writing custom filter functions

Use custom filter functions to perform any data manipulation that you cannot do with a combination of built-in filters and table objects. One of the most common uses for a custom filter function is to make a distributed function call (DFC).

Design the custom filter function to accomplish one specific task. Before developing the function, break the problem down into small steps. As you do this, you may find that you can do some, or even all, of the steps with table objects or built-in filters. When designing a custom filter function, consider reusability. All custom filter functions have a stack limit of 10K for symbols used in the function.

Do not use custom filter functions to check for empty fields or blobs. Instead, use the field object default value to place a constant value in empty fields. If required, you can then check for the default value in a field qualification object or in a production object qualification object. Use one or more built-in filters instead of custom filter functions whenever possible for faster processing results.

A custom filter function return value indicates whether or not e-Biz Impact should continue processing the transaction. A return value of “1” (one) indicates that the filter operation was successful and processing continues. A return value of “0” (zero) indicates that the filter operation was not successful, and causes the SFM to terminate transaction processing and enter the appropriate error function. If the custom filter is attached to a rule or rule component object, it enters the rule object error function; otherwise, it enters the production object error function.

When you finish entering the function, check the statement syntax and make sure your arguments are parsed correctly. The TRAN-IDE tool checks your syntax when you click OK. Syntax checking only ensures that you have not made a syntactical error in your function statements. To check the output of the function, you must test drive a transaction through the related production objects. See “Using the test drive”.

Use the buttons in the Custom Filter Function window to load or append text files to the code, and to save, print, or cancel your work. Select Public to make the function global (public).

**Table 3-4: Arguments**
Key	Description
`blob *pb`	A pointer to the current blob. In a pre-filter, the blob contains the field data the filter is acting on. In a post-filter, the blob contains the outgoing transaction that has been built up to that point.
`char mode`	The mode setting. Contains a value of “2” if you set the reverse mode, otherwise contains a value of “1”.
`string args`	A string containing the arguments that you entered in the Filter Information window.

**Table 3-5: Custom filter function keys**
Field (key)	Description
Goto Line#	Moves the cursor to the specified line of ODL text in the function. Type the line number to go to, then press enter. The ODL text editor moves the cursor to the specified line of text and highlights it. WARNING! Click once on the text or use an arrow key to unselect it before typing any characters, otherwise the selected line is replaced by the new characters.
DFC’s	View a list of the current DFC commands, click the down arrow. To define a new DFC command, click the ellipsis button. The Distributed Function Declaration window opens.
Datalinks	To view a list of the current datalink definitions, click the down arrow. To define a new datalink, click the ellipsis button. The Datalink Information window opens.
Module	To place the function into a different module, click the down arrow and select another module. If you put the function into a different module, then you must make the function public.

Alternate error return values

Use the setErrNum(), setErrTxt(), and getAlterrtext() object methods to augment the return value and error text generated by a production object custom filter, error, generic, and qualification functions. This allows you to add a unique error number and error message to each function so that you can immediately determine within which function the processing error occurred.

Use the setErrNum() and setErrTxt() methods to add an alternate error number and error message to the error text generated by the production object. You must use both of these methods for the getAlterrtext() method to function. These methods do not replace the error number and error text generated by the production object, but append extra information to the error message generated by the production object, using the format

tran error text, which can contain line feeds

the alternate error text

rv = the alternate error number

When a processing failure occurs, the alternate error values displayed are those of the last function that called one of these methods. For example, a custom filter function that calls these methods fails, and then the error function executed next also uses these methods. The error message generated by the production object contains the alternate error text set by the error function, not that set by the custom filter.

Also, when you use these methods in a function, they set the alternate error text regardless of whether or not the function encounters a processing error. Therefore, if the function that fails does not call the setErrNum() and setErrTxt() methods, but a previously executed function did, the alternate error text generated by the production object does not reflect the function where the processing failure actually occurred.

Use the getAlterrtext() method to read the alternate error number and alternate error message into an integer and string data variables. This is useful if you want to perform specific actions in the production object error function depending on which function encountered the processing error.

For detailed information about these functions, see the e-Biz Impact ODL Guide.

View this book as PDF