Programming for Error Message Output
By default, all Ingres and forms system errors are returned to the EQUEL program, and default error messages are printed on the standard output device. As discussed in the QUEL Reference Guide, you can also detect the occurrences of errors by means of the program using the inquire_ingres and inquire_frs statements. (Use the latter for checking errors after forms statements. Use inquire_ingres for all other EQUEL statements.)
This chapter discusses an additional technique that enables your program not only to detect the occurrences of errors, but also to suppress the printing of default Ingres error messages if you choose. The inquire statements detect errors but do not suppress the default messages.
This alternate technique entails creating an error-handling function in your program and passing its address to the Ingres runtime routines. Then Ingres will automatically invoke your error handler whenever a Ingres or a forms-system error occurs.
To trap Ingres errors locally, you must define an Ada error function and pass it to the EQUEL runtime routines for custom error management. The program error handler must be declared as an ADA function that can be exported. Because the Ada pragma export_function is used, the whole function must be in a package declared at the outermost scope.
The following format should be used to declare and define the function:
package Error_Trap is
function Error_Proc( err: Integer ) return Integer;
pragma export_function( Error_Proc );
end Error_Trap;
package body Error_Trap is
function Error_Proc( err: Integer ) return Integer is
begin
...
end Error_Proc;
end Error_Trap;
This function must be passed to the EQUEL procedure IIseterr for runtime bookkeeping, using the Ada statement:
IIseterr( Error_Proc'Address );
The procedure IIseterr is declared externally for you by EQUEL.
This forces all runtime Ingres errors through your function, passing the Ingres error number as an argument. If you choose to handle the error locally and suppress Ingres error message printing the function should return 0; otherwise the function should return the Ingres error number received.
Avoid issuing any EQUEL statements in a user-written error handler defined to IIseterr, except for informative messages, such as message, prompt, sleep and clear screen, and messages that close down an application, such as endforms and exit.
The example below demonstrates a typical use of an error function to warn users of access to protected tables. This example passes through all other errors for default treatment.
package Error_Trap is
function Error_Proc( ingerr: Integer ) return Integer;
pragma export_function( Error_Proc );
end Error_Trap;
with text_io; use text_io;
package body Error_Trap is
function Error_Proc( ingerr: Integer ) return Integer is
-- Error number for protected tables
TBLPROT: constant := 5003;
begin
if (ingerr = TBLPROT) then
put_line( "No authorization for operation.");
return 0; -- Suppress Ingres
-- printing message
else
return ingerr; -- Ingres will print message
end if;
end Error_Proc;
end Error_Trap;
-- In main procedure body issue the following statement
IIseterr( Error_Proc'Address );