Release 10.1A: OpenEdge Development:
Progress Dynamics Basic Development

> ## Error message checking include file (checkerr.i)

> The include file `aferrortxt.i` takes care of formatting messages into a standard format in preparation for returning them to the client to be presented to the user. As the examples above show, simply returning the message text string from any of the standard validation procedures results in the errors being processed correctly. The wrapper code that runs the validation procedures handles the messages for you.

> In other cases, however, you might need to process errors yourself (for example, from stand-alone business logic procedures that you write, as described later). There is another standard include file, called `checkerr.i`, that you should always use when checking for errors within your own logic procedure, instead of doing an `IF` `ERROR-STATUS:ERROR` check manually.

> The include file handles the checking of the error status. If an error occurred, it handles displaying of the error message or passing on of the error message and return value back to the caller. It also contains code to build a return value from the Progress Dynamics get-message method if the `RETURN-VALUE` is empty. This is a very flexible include file and should cater for all scenarios. Table 10–2 lists the named arguments.

> Table 10–2: Named arguments for checkerr.i
> Argument | Description
> --- | ---
> `&display-error = YES` | Displays the error if not in a transaction. This invokes the standard Progress Dynamics message dialog box, and should, therefore, be done only if you are in client-side code that can present the message dialog box to the user.
> `&return-only = YES` | Does not pass on the error but does a `RETURN`.
> `&return-error = YES` | Passes on the error. The code defaults to this if there is currently an open transaction.
> `&no-return = YES` | Does not return when finished; instead, this form lets you decide what to do in the code following the include file reference.
> `&ignore-errorlist = YES` | Does not use get-message errors at all (use with caution). get-message is a standard Progress Dynamics method that retrieves error messages generated by Progress, in addition to any messages generated by the application.
> `&define-only = YES` | Defines the variables you need but takes no other action. The `checkerr.i` include file defines several local variables that are needed in its processing, including `cMessageList`, `cMessageButton`, and `cMessageAnswer`, which are described below.

> The `&define-only` argument is therefore useful if `checkerr.i` is included more than once in the same file but separate procedures. If you place this code at the top of your file, the necessary variables will be defined once, and no other action will take place, as shown:

>     {checkerr.i &define-only = YES}

> When you are using `checkerr.i` in server-side business logic, normally some combination of the arguments in Table 10–2 that handle the `RETURN` statement are the ones you will use in your code. If you are displaying an error message in client code from `checkerr.i`, then arguments listed in Table 10–3 are also additionally available.

> Table 10–3: Additional arguments for checkerr.i
> Argument | Description
> --- | ---
>     &message-type
> | Type of message, one of `'MES'` (ordinary message) `'INF'` (informational message) `'WAR'` (warning) `'ERR'` (error) `'HAL'` (halt) `'QUE'` (question) The default is `'ERR'.`
>     &message-buttons
> | Comma list of buttons to be placed into the message dialog box the default is OK.
>     &button-default
> | Default button, the default is OK.
>     &button-cancel
> | Cancel button, the default is 'OK' except for `QUEstion` messages.
>     &message-title
> | Title for the message dialog box; the default is the empty string.
>     &display-empty
> | YES—Displays message dialog box even if empty, the default = `YES`.

> Table 10–4 lists the arguments available if the message type is `QUE` for `Question`.

> Table 10–4: Question arguments
> Argument | Description
> --- | ---
>     &message-data type
> | Data type, the default is `Character`.
>     &message-format
> | Format of question, the default is '`CHR(35)`.
>     &default-answer
> | Default answer, the default is empty.

> Note: For a question message type, the defaults change to `&message-buttons = 'OK,CANCEL`', `&button-default = 'OK'`, `&button-cancel = 'CANCEL'`.

> The following rules apply when you use the `checkerr.i` include file:

> - Required logical arguments must be passed unquoted as `YES` or `NO`. Other text arguments must be single quoted literals (for example, `'text'` or unquoted variables), and if the literals require spaces, they should be double-quoted then single-quoted (for example, `"'text'"`).

> - All arguments can be left blank, in which case the error will not be displayed and will be passed on with a return error.

> - If everything is left blank except `display-error` is `YES`, then the error will be displayed using the Progress Dynamics message dialog box and a standard return statement done.

> - If in a transaction, the error will be passed on regardless, unless {&no-return} is set to `YES`.

> - If display error is set to `YES`, the default is to do a return only rather than return error.

> - If display error is set to `NO`, the default is to do a return error to pass the error on.

> - If return-only is set to `YES`, this will override any other return settings and let you regain control.

> Following the include file, if `{&no-return}` is set to `YES`. Table 10–5 lists the variable values available.

> Table 10–5: NO-RETURN variables
> Variable | Value
> --- | ---
>     cMessageList
> | `CHR(3)`-delimited list of error messages.
>     cMessageButton
> | Button pressed.
>     cMessageAnswer
> | Answer if question dialog box is used.

> Here are a few examples of using the `checkerr.i` include file. First, another standard Progress Dynamics include reference is required in every procedure that uses other Progress Dynamics includes, such as `checkerr.i`. This is `afglobals.i`, which defines global references to some of the Progress Dynamics managers.

> This example runs a business logic procedure using the `launch.i` mechanism (described in more detail in Chapter 11 "Building Advanced Business Logic in a Progress Dynamics Application"). It then uses `checkerr.i` upon return to intercept any errors that occur. For the sake of simplicity, the first example simply displays the error, using the standard Progress Dynamics message dialog box, so that you can see how that works, even though you would, of course, not invoke this display directly from a server-side logic procedure.

> Here is the code that launches the procedure and a reference to `checkerr.i` to display an error, if there is one. Pass in the name of the external procedure to run persistent on the server, the name of the internal procedure to run in its handle, whether to invoke it on the AppServer, and a list of parameters to it. The internal procedure `validateDatasetQuery` uses `aferrortxt.i` to return error number `AF:114` if there is an error in the names of the input parameters. It is this error that you intercept here, as shown:

>     {afglobals.i}
>     {launch.i &PLIP = 'af/app/gscddxmlp.p'
>              &IProc = 'validateDatasetQuery'
>              &OnApp = 'NO'
>              &PList = "('rycso','rycsf','smartobject_obj,smartobject_obj','',no)"
>              &AutoKill = YES}
>     {checkerr.i &display-error = YES}           }.

> If you modify the parameter list to the `validateDatasetQuery` procedure so that it is no longer valid, an error message is generated and picked up by `checkerr.i:`

>     {afglobals.i}
>     {launch.i &PLIP = 'af/app/gscddxmlp.p'
>              &IProc = 'validateDatasetQuery'
>              &OnApp = 'NO'
>              &PList = "('rycso','rycsf','smartobject_obj,smartxxxxx_obj','',no)"
>              &AutoKill = YES}
>     {checkerr.i &display-error = YES}.

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095