1. Overview. In this lesson, you will use Display.DisplayFormVIP to fill in the data on the help from the previous lesson.

2. What You'll Use. You will use your text editor and the Ada compiler. The following new Sage-ST calls will be used:

Display.DisplayFormVIP
Calls.D_Check

3. Assignment. The UserHelp implemented in the previous lesson provided a very simple demonstration of the package, but there was nothing done that could not have been done more easily using regular help forms. However, this sets the stage for what we are about to do.

There are several problems with what was done in the previous lesson: hard coding data that is subject to change is not recommended; there could easily be more organization numbers than would conveniently fit onto a help form; if the user discovers that the needed organization is not available, they must back out to the main menu, use the organization edit to add the new organization, and then return to editing employee data. A properly organized UserHelp using Display.DisplayFormVIP will eliminate all these problems.

Carefully read the information on Display.DisplayFormVIP in the Reference Manual in Volume 2. Revise your help form such that there is no data on it.

Substitute the DisplayFormVIP call for the DisplayForm call. Other than that, you do not need to change any forms or existing code; however, you will need to create and instantiate a short procedure that DisplayFormVIP will use to fill up the screen. This procedure will be referred to as the portrait for the VIP form. In our solution we also implemented a "hot key" capability for adding new organizations.

Please note a new variable, which is global within the HelpLib package. The variable "buffer" is a string of length 135 that identifies the total highlight area on the form (5 rows of 27 characters). It is important that what you write about "buffer" exactly matches what you have drawn on ScrlEmp.

The hardest part about understanding DisplayFormVIP is understanding the parameters being passed into the Variable input procedure. When you call DisplayFormVIP, control passes to Sage-ST. At some point, Sage-ST realizes it needs data to display to the form you specified, so Sage-ST calls your procedure. When it does, it passes in the record number of the first record it wants and how many records it wants altogether. Suppose there are ten lines on the ScrlEmp form. When DisplayFormVIP is called initially, it will pass in the number 1 as the first parameter (the first record it wants), and the number 5 as the second (how many records it wants). It is then up to you to fill up the buffer with five records, beginning with record #1, and pass back to Sage-ST the SYSTEM'address of the buffer (the third parameter of the procedure).

So now the user is looking at portions of the first five records in the employee relation. The user presses <PgDn> to see the next five records--records 6 through 10. Sage-ST detects the <PgDn> and calls your procedure in order to fill up buffer with new data. The first parameter, recNum, will be 6 (start with record #11); the second parameter, recTot, will be 5 (and give Sage-ST five records). You fill up buffer, Sage-ST displays it, and the user sees records 5 through 10.

Now let's suppose that the user cursors down through the list, gets to the bottom (record #10) and arrows down one more. What should now be displayed are records 7 through 11. Sage-ST detects the down arrow and calls your procedure. But Sage-ST recognizes that it already has records 7 through 10; all it needs is record #11. Therefore, recNum will be 11, and recTot will be 1.

The following are some common problems encountered in this lesson:

1. The data is all there, but the entries don't begin at the beginning of their respective lines. Instead they slant from top left to bottom right, or top right to bottom left. Buffer must accurately reflect the available space of the form. Check the length of the line on your form with what you have said in your code.

2. Everything looks great--except that the last part of each line is missing. You may have noticed in the code that there are two places where either the buffer or the string are filled with blanks. Sage-ST recognizes ASCII.nuls as indicating the end of a string; therefore, if one gets into your string, Sage-ST assumes that it has reached the end of the string.

4. Our Solution.

AddOrg Add org form 2 Field(s)
packed picture size -> 39 bytes
predominant color -> light cyan on black
-----------------------------------------------------------------------------
╔═════════════════════════════╗
║ ░1░░ ░░░░░░░░░2░░░░░░░░░░ ║
╚═════════════════════════════╝
-----------------------------------------------------------------------------
Field Display Type Record & (Field) - rpt Field Type Help Frm
----- ------------- ---------------------- ---------------------- --------
1 Entry/Display Org (OrgNum) - 1 Alpha/Numbers
2 Entry/Display Org (Des) - 1 Alphanumeric

HpDeptV scrolling hp form--org number 5 Field(s)
packed picture size -> 213 bytes
predominant color -> light cyan on black
------------------------------------------------------------------------------
4C00 Technology Transfer
4C10 Special Applications
4C20 Scientific Computing
4C30 Env./Waste Mgmt. Comp.
4C50 Ind. Verification/Val.
<F2> - Add Org

-----------------------------------------------------------------------------
Field Display Type Record & (Field) - rpt Field Type Help Frm
----- ------------- ---------------------- ---------------------- --------
1 Highlighted Employee(OrgNum) - 1 Alpha/Numbers
2 Highlighted Employee(OrgNum) - 1 Alpha/Numbers
3 Highlighted Employee(OrgNum) - 1 Alpha/Numbers
4 Highlighted Employee(OrgNum) - 1 Alpha/Numbers
5 Highlighted Employee(OrgNum) - 1 Alpha/Numbers


with Calls ;
with Display;
with ModSys ;
with Sage ;
with SYSTEM ;


package body HelpLib is


procedure UserHelp (currentForm : in string;
currentRelation : in string;
currentField : in string;
fieldRepeat : in ModSys.S_natural;
occurenceNumber : in ModSys.S_natural) is

buffer : string(1..135);

procedure Load_Buffer (recNum : in ModSys.S_natural;
recNeed : in ModSys.S_natural;
bLoc : in out SYSTEM.address) is

begin

buffer := (others => ' ');

for index in 1..recNeed loop

Sage.ReadRecordN ("Org", "OrgNum", ModSys.S_long_integer(RecNum+index-1));
Sage.GetFieldA ("Org", "OrgNum",
buffer(((index-1)*27 + 1)..((index-1)*27 + 4)));
Sage.GetFieldA ("Org", "Des",
buffer(((index-1)*27 + 8)..((index-1)*27 + 27)));

end loop;

bLoc := buffer'address;

end Load_Buffer;


function Org_List is new Calls.D_Check (Load_Buffer);

begin

-- The required USERHELP processing goes here
loop

Display.DisplayFormVIP ("HpDeptV", "", "", false, Org_List, 27,
ModSys.S_natural(Sage.TotalRecords("Org")),
"Employee", "OrgNum");

case Display.LastExitFunction is

when 10 => -- normal exit, quit loop
exit;

when 41 => -- add requested for org
Sage.ReadRecordN ("Org", "OrgNum",
ModSys.S_long_integer(Display.VariableIndex));
Display.DisplayForm ("AddOrg", "Org", "OrgNum", false);
Sage.WriteRecord ("Org");
if (Sage.SageError = 0) then
Display.DisplayMessage ("Org added.", false);
else
Display.DisplayMessage ("Unable to add org.", true);
end if;

when 42 => -- modify is not allowed
null;

when 43 => -- delete is not allowed
null;

when others => -- do nothing
null;

end case;

end loop;

Display.DisplayBackground(currentForm,false);

end UserHelp;

end HelpLib;