Reports

Intercept Routines

Sage-ST ^TM allows the user to intercept key presses and/or the processing flow in a number of ways. Detailed below are the various packages that provide that capability and some description of their use.

The package CheckLib allows the application to intercept the processing flow as a user is entering or leaving fields. In the routines values can be checked and the user informed if they have made an invalid entry.

The package FormChk allows the application to intercept each key pressed by the user and to allow, replace or disallow that key. One very useful application of this is when the user is attempting to enter password values in a field. The application can track the keys pressed to check the accuracy of the password entered but can substitute other chacters such as a '*' to show in the forms field.

The package HelpLib allows the application to intercept the call to help (default key is F1). When this routine is called the application can determine what help to show the user. This is done by checking the values passed into the routine. They provide enough information for the routine to know where the user was located when help was called.

The package MsgChk allows the application to intercept messages which are about to be shown to the user resulting from a fatal error occurring. In this routine the application can change the message text or suppress the error.

Listed below are each of the packages with simple examples of how they are called.

CheckLib

If the default routines of CheckLib are to be used then no action is necessary in the application. However if you would like to use your own routines in place of the defaults here is what you must do:

1) Create a package that looks just like the CheckLib package. However the package must be a different name. Click here to see the specification of the two routines. The routines may or may not be named the same as the original CheckLib routines. However the number and type of parameters MUST match exactly the original routines. Only the package name must be different.

2) Call the appropriate routine to set your procedures as the new default to call when needed (see below). The 'access statement is simply Ada95 syntax which passes the name of a routine to another routine. The parameters of the routine being passed must match the exact format and type of parameters that are defined in the CheckLib package spec.

CheckLib provides two routines. The first, called FieldEntry is executed within SAGE each time a new field on a form is entered. It allows the programmer to perform any tasks, such as displaying a message, which may be associated with the field being entered. This routine is called AFTER the system is opened.

Example call:

      Sage.OpenSystem (Dictionary => "MYDFL.DFL",
      MaxForms => 5,
      MaxScreens => 5,
      BufferSize => 10_000);
      if Sage.SageError = 0 then
      Sage.DefineFormFieldEntryProc (FieldEntryProc => CheckAll.FieldEntry'access);
      end if;

The second routine, called FieldCheck allows programmers to supply their own field validation algorithms. By default, FieldCheck is called each time the contents of a field on a form are changed before the cursor is directed to another field. To change this so that this procedure is called every time the cursor leaves the field, the Display.ForceFieldCheck is set to TRUE (FALSE by default).

Calls to such procedures as 'Sage.GetFieldA' and other data base procedures may be made to retrieve the new contents. If the new contents are unacceptable, this function should return FALSE. When this happens, the cursor will not be allowed to leave the field until the contents are acceptable. It is recommended that Display.DisplayMessage be used liberally to inform the user of any errors.

There are actually several variations to this call. They are shown and explained in comments before each call.

Example call:

      Sage.OpenSystem (Dictionary => "MYDFL.DFL",
      MaxForms => 5,
      MaxScreens => 5,
      BufferSize => 10_000);
      if Sage.SageError = 0 then
      -- All the systems fields will trigger a call to this same routine.
      Sage.DefineSystemCheck (CheckProc => CheckAll.FieldCheck'access);
      -- Only the fields of this specific Relation will trigger a call to
      -- this routine. Each relation could have a different routine called
      -- for validation.
      Sage.DefineRecordCheck (Relation => "MYREL",
      CheckProc => CheckAll.MyRelCheck'access);
      -- Only the field of this specific Relation and Field will trigger a
      -- call to this routine. Each field in the schema could have a
      -- different routine called for validation.
      Sage.DefineFieldCheck (Relation => "MYREL",
      Field => "MYFLD",
      CheckProc => CheckAll.MyRelFldCheck'access);
      end if;

FormChk

If the default routine of FormChk is to be used then no action is necessary in the application. However if you would like to use your own routine in place of the default here is what you must do:

1) Create a package that looks just like the FormChk package. However the package must be a different name. Click here to see the specification of the routine. The routine may or may not be named the same as the original FormChk routine. However the number and type of parameters MUST match exactly the original routine. Only the package name must be different.

2) Call the appropriate routine to set your procedure as the new default to call when needed (see below). The 'access statement is simply Ada95 syntax which passes the name of a routine to another routine. The parameters of the routine being passed must match the exact format and type of parameters that are defined in the FormChk package spec.

FormChk has only one routine. It is called FormIntercept and is executed within SAGE during normal form processing during the time that a user keystroke is awaited or when a keystroke is detected. This procedure may be used to intercept that processing for such purposes as timing, key evaluation before processing, etc.

If you supply your own procedure here, while in a form that you do not require interception capabilities, the keyboard response can be considerably speeded up by immediately returning 'inhibitIntercept' as TRUE.

Additional information about the field of the form in which the cursor is resident may be obtained from procedures in the InfoLib package.

Example call:

      Sage.OpenSystem (Dictionary => "MYDFL.DFL",
      MaxForms => 5,
      MaxScreens => 5,
      BufferSize => 10_000);
      if Sage.SageError = 0 then
      Sage.DefineFormIntercept (InterceptProc => MyFrmChk.FormIntercept'access);
      end if;

HelpLib

If the default routine of HelpLib is to be used then no action is necessary in the application. However if you would like to use your own routine in place of the default here is what you must do:

1) Create a package that looks just like the HelpLib package. However the package must be a different name. Click here to see the specification of the routine. The routine may or may not be named the same as the original HelpLib routine. However the number and type of parameters MUST match exactly the original routine. Only the package name must be different.

HelpLib has only one routine. It is called UserHelp and is executed within SAGE upon a USERHELP request from the form. There are two ways in which the user may request this type of help. These are 1) The programmer has defined the 'userhelp' (#38) function using 'Display.DefineFunctionKey' and the user depressed the defined key. 2) A help form with the predefined name 'USERHELP' was defined in THOR as the form requested from the current location when the help key is depressed. (Note: 'USERHELP' is a reserved form name, as are 'EXIT' and 'HALT').

Any normal procedure calls may be made within this procedure to display additional forms, operate on a data base, etc. When this procedure is terminated, the program control will return to the same form location from which the USERHELP was invoked just as if a normal help form were requested and terminated.

Example call:

      Sage.OpenSystem (Dictionary => "MYDFL.DFL",
      MaxForms => 5,
      MaxScreens => 5,
      BufferSize => 10_000);
      if Sage.SageError = 0 then
      Display.DefineUserHelp (HelpProcedure => MyHelp.MyUserHelp'access);
      end if;

MsgChk

If the default routine of MsgChk is to be used then no action is necessary in the application. However if you would like to use your own routine in place of the default here is what you must do:

1) Create a package that looks just like the MsgChk package. However the package must be a different name. Click here to see the specification of the routine. The routine may or may not be named the same as the original MsgChk routine. However the number and type of parameters MUST match exactly the original routine. Only the package name must be different.

MsgChk has only one routine. It is called MessageIntercept and is executed within SAGE prior to displaying any error message from within a form. The error number, message contents, and/or instructions to ring the bell may be changed.

A programmer may replace this package and procedure with one of his own to perform required functions. The one currently used in Sage does nothing and is only provided to allow the programmer to intercept messages.

Example call:

      Sage.OpenSystem (Dictionary => "MYDFL.DFL",
      MaxForms => 5,
      MaxScreens => 5,
      BufferSize => 10_000);
      if Sage.SageError = 0 then
      Sage.DefineMessageIntercept (MessageProc => MyMsg.MyMsgProc'access);
      end if;