|
|
|
|
subtype HelpProc is SageSpec.HProcType;
type HPROC is access
procedure (currentForm : in System.Address;
CurrentForm_High : in ModSys.S_Natural;
currentRelation : in System.Address;
CurrentRelation_High : in ModSys.S_Natural;
currentField : in System.Address;
CurrentField_High : in ModSys.S_Natural;
fieldRepeat : in ModSys.S_Natural;
OccurrenceNumber : in ModSys.S_Natural);
pragma Convention
(WIN32,
HPROC);
procedure AutoClearField
(enabled : in boolean);
--*
-- AutoClearField - Automatically clear field, on new data entry.
--
--
-- This procedure alters the default editing mode behavior for
-- "display/entry" type fields on SAGE forms. When "AutoClearField"
-- mode is disabled (the default SAGE mode), form "display/entry" type
-- fields operate in an "overwrite" type mode. When the cursor
-- enters a form field that contains existing data, the user may
-- overwrite part of the field data, without affecting the remaining
-- data. When the user exits the field, the current field data is
-- accepted and processed by the form logic.
--
-- When "AutoClearField" mode is enabled, form "display/entry" type
-- fields operate in a "clear and overwrite" type mode. When the cursor
-- enters a form field, if a non SAGE function type key is pressed,
-- the field is automatically cleared, and the typed character is
-- displayed in the field. (SAGE function keys include such keys
-- as "rightArrow", "leftArrow", etc.) If the user enters a SAGE
-- function key (such as rightArrow) as the first key in the field,
-- the field will not be cleared and will behave as if the
-- "AutoClearField" mode were disabled. Thus, to achive an
-- "overwrite" on existing field data (while "AutoClearField" is
-- enabled), the user may type a "rightArrow", "leftArrow" combination,
-- before entering the new field data. (The leftArrow key is only
-- required if you want to start editing in the first character position
-- of the field.)
--
-- CALLING SEQUENCE -
--
-- AutoClearField (True)
--
-- ENTRY -
--
-- Enabled : BOOLEAN
-- If Enabled = TRUE, enable the "AutoClearField" mode for form
-- "display/entry" type fields. Otherwise, disable the
-- "AutoClearField" mode.
--
procedure ChangeFormField
(FormName : in string;
Relation : in string;
Field : in string;
entryType : in ModSys.S_Integer;
standardAppearance : in ModSys.S_Integer;
highlightAppearance : in ModSys.S_Integer);
--*
-- ChangeFormField - Change attributes of a form field.
--
--
-- This procedure allows the changing of the attributes of a
-- field on the form for as long as the form appears in memory.
-- Since the changed values are only true as long as the form is
-- in memory, it should be used while already in a form or just
-- prior to displaying a form. Otherwise, accessing other
-- relations or displaying other forms may cause the form in
-- question to be released from memory and thus revert back to
-- the original form's definition.
--
-- Following is a list of the appearances associated with the integers
-- 0-255. These are used for the standardAppearance and
-- highlightAppearance parameters.
--
-- appear. foreground background
-- ------ ---------- ----------
-- 0 black black
-- 1 blue black
-- 2 green black
-- 3 cyan black
-- 4 red black
-- 5 magenta black
-- 6 brown black
-- 7 white black
-- 8 gray black
-- 9 light blue black
-- 10 light green black
-- 11 light cyan black
-- 12 light red black
-- 13 light magenta black
-- 14 yellow black
-- 15 light white black
-- 16..31 (same as 0..15) blue
-- 32..47 (same as 0..15) green
-- 48..63 (same as 0..15) cyan
-- 64..79 (same as 0..15) red
-- 80..95 (same as 0..15) magenta
-- 96..111 (same as 0..15) brown
-- 112..127 (same as 0..15) white
-- 128..255 (same as 0..127 except blink foreground)
--
-- CALLING SEQUENCE -
--
-- ChangeFormField (formName, relation, field, entryType,
-- standardAppearance, highlightAppearance)
--
-- ENTRY -
--
-- formName : string
-- Name of form which contains fields to change.
--
-- relation : string
-- Name of relation in which specified field resides.
--
-- field : string
-- Name of field (repeat value in [] is optional) in indicated relation.
--
-- entryType : ModSys.S_integer
-- New value of field entry type -
-- -1 = keep current entry type
-- 0 = display only
-- 1 = entry and display
-- 2 = highlighted
--
-- standardAppearance : ModSys.S_integer
-- New appearance for the field (0..255) or (-1) if the current
-- standard appearance should be used without change.
--
-- highlightAppearance : ModSys.S_integer
-- New highlight appearance for the field (0..255) or (-1) if the
-- current highlight appearance should be used without change.
--
-- EXIT -
--
-- Sage.SageError : ModSys.S_natural
-- An error flag indicating the result of the operation.
--
procedure ClearColorScheme; --* -- ClearColorScheme - Clear the color scheme table. -- -- -- This procedure clears the color scheme table of all entries. -- For an explanation of this refer to the 'DefineColorScheme' -- procedure. -- -- CALLING SEQUENCE - -- -- ClearColorScheme; --
procedure CopyScreen
(FileName : in string);
--*
-- CopyScreen - Copy the current contents of the screen to a file.
--
--
-- This procedure copies the current contents of the screen to the
-- end of the file named in "fileName." An ASCIIX.FF (form feed)
-- character is written following the last 'screen' written to the
-- file.
--
-- CALLING SEQUENCE -
--
-- CopyScreen (fileName)
--
-- ENTRY -
--
-- fileName : string
-- Name of file to write 'screen image' to.
--
procedure DefineColorScheme
(schemeName : in string;
replacementColor : in ModSys.S_Integer);
--*
-- DefineColorScheme - Change named standard color on forms.
--
--
-- This procedure causes the colors on forms to be displayed to be
-- redefined. Any color on a form which is displayed after this
-- procedure is executed and which corresponds to the original
-- 'schemeName' color will be converted to the 'replacementColor'.
-- To deactivate this replacement process, execute the
-- 'ClearColorScheme' procedure.
--
-- The color characters are 8 bit entities with each bit
-- having a meaning as follows:
--
-- BIT MEANING (1=ON, 0=OFF)
-- --- -----------------------------
-- 0 Foreground blue
-- 1 Foreground green
-- 2 Foreground red
-- 3 Foreground intensity (1=hi, 0=lo)
-- 4 Background blue
-- 5 Background green
-- 6 Background red
-- 7 Foreground blinking
--
-- By using a combination of settings, various colors and effects
-- may be generated. For example:
--
-- COLOR BITS SET CHAR. #
-- ------ --------------------- -------
-- light red on black 2 3 12
-- dark green on yellow 1 5 6 98
-- yellow on black 1 2 3 14
-- cyan on red 0 1 3 6 75
-- magenta on black 0 2 3 13
-- white on black 0 1 2 3 15
-- black on white 4 5 6 112
--
-- CALLING SEQUENCE -
--
-- DefineColorScheme (schemeName, replacementColor)
--
-- ENTRY -
--
-- schemeName : string
-- Standard scheme name representing the color to change on the forms.
--
-- replacementColor : ModSys.S_integer
-- Color to replace 'schemeName' color wherever it appears on the form.
--
-- EXIT -
--
-- Sage.SageError : ModSys.S_natural
-- An error flag indicating the result of the operation.
--
procedure DefineColorSwap
(originalColor : in ModSys.S_Integer;
replacementColor : in ModSys.S_Integer);
--*
-- DefineColorSwap - Define color element of std color table.
--
--
-- This procedure defines a color element of the standard color
-- table which is used to redefine colors on forms to be displayed.
-- Any 'originalColor' on a form which is displayed after this
-- procedure is executed will be converted to the 'replacementColor'.
-- To deactivate this replacement process, execute this procedure
-- with the same value for the 'originalColor' and the
-- 'replacementColor'.
--
-- The color characters are 8 bit entities with each bit
-- having a meaning as follows:
--
-- BIT MEANING (1=ON, 0=OFF)
-- --- -----------------------------
-- 0 Foreground blue
-- 1 Foreground green
-- 2 Foreground red
-- 3 Foreground intensity (1=hi, 0=lo)
-- 4 Background blue
-- 5 Background green
-- 6 Background red
-- 7 Foreground blinking
--
-- By using a combination of settings, various colors and effects
-- may be generated. For example:
--
-- COLOR BITS SET CHAR. #
-- ------ --------------------- -------
-- light red on black 2 3 12
-- dark green on yellow 1 5 6 98
-- yellow on black 1 2 3 14
-- cyan on red 0 1 3 6 75
-- magenta on black 0 2 3 13
-- white on black 0 1 2 3 15
-- black on white 4 5 6 112
--
-- CALLING SEQUENCE -
--
-- DefineColorSwap (originalColor, replacementColor)
--
-- ENTRY -
--
-- originalColor : ModSys.S_integer
-- The color to be replaced wherever it appears on the form.
--
-- replacementColor : ModSys.S_integer
-- Color to replace 'originalColor' wherever it appears on the form.
--
procedure DefineFormIntercept
(InterceptProc : in SageSpec.IProcType);
--*
-- DefineFormIntercept - Define keystroke intercept routine for a form.
--
--
-- This routine used to be found in FormChk using the Alsys compiler's
-- alternate body command.
--
procedure DefineFormFieldEntryProc
(FieldEntryProc : in SageSpec.EProcType);
--*
-- DefineFormFieldEntryProc - Define procedure to be executed upon field entry.
--
--
-- This procedure allows the definition of a procedure to be executed
-- each time a new field on a form is entered. This routine used to be
-- found in CheckLib using the Alsys compiler's alternate body command.
--
-- CALLING SEQUENCE -
--
-- DefineFormFieldEntryProc (FieldEntryProc)
--
-- ENTRY -
--
-- EntryProc : SageSpec.EProcType
-- The name of the procedure to execute. This procedure
-- must be of the format of the EPROC type.
--
procedure RemoveFormIntercept; --* -- RemoveFormIntercept - Remove the form intercept request. -- -- -- This procedure remove the current form intercept procedure -- execution defined by the 'DefineFormIntercept' procedure. This -- is the default case. -- -- CALLING SEQUENCE - -- -- RemoveFormIntercept --
procedure DefineFunctionKey
(keyNumber : in ModSys.S_Natural;
c1 : in character;
c2 : in character);
--*
-- DefineFunctionKey - Redefine key used in forms.
--
--
-- This procedure allows the redefinition or assignment of a key
-- to a form function. If another function has already been
-- assigned to the key pair being submitted for the current
-- function, that alternate function is deactivated (or set to
-- ASCIIX.nul, ASCIIX.nul). The setting of a function to two
-- ASCIIX.nul characters deactivates that function. The following
-- table gives an example of the C1 and C2 values for various
-- keys. Other key function combinations are described in your
-- DOS technical reference manual.
--
-- key c1'val/c2'val key c1'val/c2'val
-- ------- ------------- ------- -------------
-- cr 13, 0 Ctrl-A 1 , 0
-- esc 27, 0 Ctrl-B 2 , 0
-- ' ' 32, 0 Ctrl-C 3 , 0
-- '0' 48, 0 Ctrl-D 4 , 0
-- 'A' 65, 0 Ctrl-E 5 , 0
-- 'a' 97, 0 Ctrl-F 6 , 0
-- Ctrl-G 7 , 0
-- Alt-A 0, 30 Ctrl-H 8 , 0
-- Alt-B 0, 48 Ctrl-I 9 , 0
-- Alt-C 0, 46 Ctrl-J 10, 0
-- Alt-D 0, 32 Ctrl-K 11, 0
-- Alt-E 0, 18 Ctrl-L 12, 0
-- Alt-F 0, 33 Ctrl-M 13, 0
-- Alt-G 0, 34 Ctrl-N 14, 0
-- Alt-H 0, 35 Ctrl-O 15, 0
-- Alt-I 0, 23 Ctrl-P 16, 0
-- Alt-J 0, 36 Ctrl-Q 17, 0
-- Alt-K 0, 37 Ctrl-R 18, 0
-- Alt-L 0, 38 Ctrl-S 19, 0
-- Alt-M 0, 50 Ctrl-T 20, 0
-- Alt-N 0, 49 Ctrl-U 21, 0
-- Alt-O 0, 24 Ctrl-V 22, 0
-- Alt-P 0, 25 Ctrl-W 23, 0
-- Alt-Q 0, 16 Ctrl-X 24, 0
-- Alt-R 0, 19 Ctrl-Y 25, 0
-- Alt-S 0, 31 Ctrl-Z 26, 0
-- Alt-T 0, 20
-- Alt-U 0, 22 Ctrl-F1 0, 94
-- Alt-V 0, 47 Ctrl-F2 0, 95
-- Alt-W 0, 17 Ctrl-F3 0, 96
-- Alt-X 0, 45 Ctrl-F4 0, 97
-- Alt-Y 0, 21 Ctrl-F5 0, 98
-- Alt-Z 0, 44 Ctrl-F6 0, 99
-- Ctrl-F7 0, 100
-- Alt-F1 0, 104 Ctrl-F8 0, 101
-- Alt-F2 0, 105 Ctrl-F9 0, 102
-- Alt-F3 0, 106 Ctrl-F10 0, 103
-- Alt-F4 0, 107 Ctrl-F11 0, 137
-- Alt-F5 0, 108 Ctrl-F12 0, 138
-- Alt-F6 0, 109
-- Alt-F7 0, 110 Ctrl-PrtSc 0, 114
-- Alt-F8 0, 111 Ctrl-Left Ar.0, 115
-- Alt-F9 0, 112 Ctrl-Rght Ar.0, 116
-- Alt-F10 0, 113 Ctrl-End 0, 117
-- Alt-F11 0, 139 Ctrl-PgDn 0, 118
-- Alt-F12 0, 140 Ctrl-Home 0, 119
-- Ctrl-PgUp 0, 132
-- Alt-1 0, 120
-- Alt-2 0, 121 F1 0, 59
-- Alt-3 0, 122 F2 0, 60
-- Alt-4 0, 123 F3 0, 61
-- Alt-5 0, 124 F4 0, 62
-- Alt-6 0, 125 F5 0, 63
-- Alt-7 0, 126 F6 0, 64
-- Alt-8 0, 127 F7 0, 65
-- Alt-9 0, 128 F8 0, 66
-- Alt-0 0, 129 F9 0, 67
-- Alt-- 0, 130 F10 0, 68
-- Alt-_ 0, 131 F11 0, 133
-- F12 0, 134
-- Home 0, 71
-- up arrow 0, 72
-- PgUp 0, 73 Shift-F1 0, 84
-- - 0, 74 Shift-F2 0, 85
-- left arrow 0, 75 Shift-F3 0, 86
-- right arrow 0, 77 Shift-F4 0, 87
-- + 0, 78 Shift-F5 0, 88
-- End 0, 79 Shift-F6 0, 89
-- down arrow 0, 80 Shift-F7 0, 90
-- PgDn 0, 81 Shift-F8 0, 91
-- Ins 0, 82 Shift-F9 0, 92
-- Del 0, 83 Shift-F10 0, 93
-- Shift-F11 0, 135
-- Shift-F12 0, 136
--
-- The following are the SAGE functions by number.
--
-- SAGE
-- No. function Description Default Key(s)
-- ----- ------------- ------------------------------- --------------------
--
-- 1 forward move cursor forward 1 position right arrow
-- 2 backward move cursor back 1 position left arrow/backspace
-- 3 up move cursor up 1 line up arrow
-- 4 down move cursor down 1 line down arrow
-- 5 tab tab to next entry field tab
-- 6 backtab back tab to previous field shift/tab
-- 7 restore restore field to original value Ctrl/R
-- 8 helpexit exit to associated help form Esc
-- 9 home go to first field on form Home
-- 10 exit leave form Enter
-- 11 clearall clear all fields on form Ctrl/Home
-- 12 clearfield clear field from cursor Ctrl/End
-- 13 bw toggle between B&W/color Ctrl/B
-- 14 help user help for key functions Alt/H
-- 15 insert insert mode Ins
-- 16 delete delete a character Del
-- 17 copyscreen copy screen to file SCREEN.CPY Ctrl/K
-- 18 pagedown variable field page down PgDn
-- 19 pageup variable field page up PgUp
-- 20 helpabort exit help form F10
-- 21-30 exit1-exit10 special exit functions [programmer-defined]
-- 31 firstpage variable field first page Ctrl/PgUp
-- 32 lastpage variable field last page Ctrl/PgDn
-- 33 genhelpexit exit to general help form [programmer-defined]
-- 34 fieldInfo form/relation/field info Ctrl/F
-- 36 autoHELP toggle auto helps on and off Alt/A
-- 37 haltForms exit all stacked forms [programmer-defined]
-- 38 userHelp invoke special user help [programmer-defined]
-- 39 exitAndReset exit form & reset to prior values [programmer-defined]
-- 40 clearStart go to start of field and clear field
-- 41-60 exit11-exit30 special exit functions [programmer-defined]
--
-- CALLING SEQUENCE -
--
-- DefineFunctionKey (keyNumber, c1, c2)
--
-- ENTRY -
--
-- keyNumber : ModSys.S_natural
-- Number of key function to redefine.
--
-- c1 : character
-- The first character used to define the specified function.
--
-- c2 : character
-- The second character of the pair if the first is ASCIIX.nul.
--
-- EXAMPLE -
--
-- begin
-- -- define the special exit 1 key to be invoked by F1
--
-- Display.DefineFunctionKey (21,character'val(0),character'val(59));
--
-- -- define the special exit 2 key to be invoked by F2
--
-- Display.DefineFunctionKey (22,character'val(0),character'val(60));
--
-- Display.DisplayForm ("FormName","RelName","FldName",false);
--
-- -- evaluate which key was used to terminate the form
--
-- if (Display.LastExitFunction = 21) then
-- -- special operation matching the execution of the F1 key
-- elsif (Display.LastExitFunction = 22) then
-- -- special operation matching the execution of the F2 key
-- elsif (Display.LastExitFunction = 10) then
-- -- processing of normal form exit
-- end if;
--
procedure GetFunctionKey
(keyNumber : in ModSys.S_Natural;
c1 : in out character;
c2 : in out character);
--*
-- GetFunctionKey - Get the key for the function.
--
--
-- This procedure gets the key value that is currently associated
-- with a function. If both values are nul then the function does
-- not currently have a key assigned to it. However some key values
-- have the first character as nul so both characters must be checked
-- to ensure that this is the case.
--
-- See the DefineFunctionKey documentation for more information
-- about function keys.
--
-- CALLING SEQUENCE -
--
-- GetFunctionKey (keyNumber, c1, c2)
--
-- ENTRY -
--
-- keyNumber : CARDINAL
-- Number of key function to redefine.
--
-- EXIT -
--
-- c1 : CHAR
-- The first character used to define the specified function.
-- If this is set to nul, then the second char has to be checked
-- to see if it is nul.
--
-- c2 : CHAR
-- The second character of the pair.
--
procedure DefineUserHelp
(HelpProcedure : in HelpProc);
--*
-- DefineUserHelp - Define the user help procedure.
--
--
-- This procedure provides for the definition of a user help
-- procedure whenever the USERHELP function is invoked by
-- the user in one of the following ways -
--
-- 1) A help form with the reserved name, USERHELP, is
-- defined and then encountered during form processing
-- by the user.
--
-- 2) The 'userHelp' function key (# 38) has been activated
-- by the current program using 'Display.DefineFunctionKey'
-- and the user presses the associated key.
--
-- Any normal procedure calls may be made within this procedure
-- (HelpProc) 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.
--
-- The USERHELP option may be deactivated using the
-- 'Display.RemoveUserHelp' procedure.
--
-- This routine used to be found in HelpLib using the Alsys compiler's
-- alternate body command.
--
-- CALLING SEQUENCE -
--
-- DefineUserHelp (HelpProc)
--
-- ENTRY -
--
-- HelpProc : HPROC
-- The procedure to be executed when USERHELP is invoked.
--
procedure RemoveUserHelp; --* -- RemoveUserHelp - Remove the call to user help. -- -- -- This procedure removes the procedure currently defined for -- user help. -- -- CALLING SEQUENCE - -- -- RemoveUserHelp; --
procedure DefineVariableArray
(FormName : in string;
v_Proc : in SageSpec.VProcType;
recordSize : in ModSys.S_Natural;
recordNum : in ModSys.S_Natural;
variableRecord : in string;
variableField : in string);
--*
-- DefineVariableArray - Define array to drive var. field form.
--
--
-- This procedure allows the definition of a procedure which
-- supplies an array to drive the variable fields of a form.
-- This is useful if the form is a help form and cannot be
-- defined by calling one of the 'DisplayFormV...' procedures.
-- Many form/procedure pair ups may be made by successive calls
-- to this procedure before 'DisplayFormVIP' or 'DisplayFormV'
-- are called. 'DisplayFormV' or 'DisplayFormVIP' use these
-- definitions if any of the forms so defined are invoked. They
-- then release all form/array pair definitions when control is
-- returned to the program.
--
-- NOTE: The fieldBuffer must be global to the package in which it
-- is declared, and the procedure used to fill the array cannot be
-- nested.
--
-- CALLING SEQUENCE -
--
-- DefineVariableArray (formName, ABC, recordSize, recordNum,
-- variableRecord, variableField)
--
-- ENTRY -
--
-- formName : string
-- Name of form.
--
-- vProc : SageSpec.VProcType
-- Procedure which returns the address of the data to be shown on the
-- form.
--
-- recordSize : ModSys.S_natural
-- The character size of each record in the fieldBuffer.
--
-- recordNum : ModSys.S_Natural
-- The number of records of size "recordSize" to be displayed.
--
-- variableRecord : string
-- The record part of the variable field definition.
--
-- variableField : string
-- Name of the field(s) on the form to have their contents varied by the
-- contents of the fieldBuffer. This field must be a highlighted field.
--
-- EXIT -
--
-- Sage.SageError : ModSys.S_natural
-- An error flag indicating the result of the operation.
--
-- EXAMPLE -
--
-- with Sage;
-- with Calls;
--
-- procedure Test is
--
-- buf : string (1..100);
--
-- procedure MyDataLoad
-- (recNum : in ModSys.S_Natural;
-- recNeed : in ModSys.S_Natural;
-- bLoc : in out System.Address) is
-- begin
-- -- this procedure loads the 'buf' string with data
-- bLoc := buf'address;
-- end MyDataLoad;
--
-- procedure A
-- (recNum : in ModSys.S_Natural;
-- recNeed : in ModSys.S_Natural;
-- bLoc : in out System.Address) is
-- begin
-- -- this procedure loads the 'buf' string with data
-- bLoc := buf'address;
-- end A;
--
-- function Picture_Load is new Calls.D_Check (MyDataLoad);
-- function ABC is new Calls.D_Check (A);
--
-- begin
-- DefineVariableArray ("Help1",ABC,5,100,"Rel2","Fld");
-- Display.DisplayFormVIP ("TestForm", "RelName", "FldName", FALSE,
-- Picture_Load, 10,1000,"RelName", "VarField");
--
procedure DefineWindowLoc
(FormName : in string;
row : in ModSys.S_Natural;
col : in ModSys.S_Natural);
--*
-- DefineWindowLoc - Temporarily define new form window location.
--
--
-- This procedure allows the relocation of a given form location
-- on the screen. The form's height and width cannot be changed
-- from the original definition. If the new location will not
-- allow enough space for the form, its position is not
-- redefined and a 27 error is returned. This procedure must be
-- called just before the 'DisplayForm' procedure is called since
-- it does not change the original form location on the schema
-- file and dynamic loading is always occurring in the Sage
-- system.
--
-- The top, left corner of the screen is defined as row 1, column 1.
--
-- CALLING SEQUENCE -
--
-- DefineWindowLoc (formName, row, col)
--
-- ENTRY -
--
-- formName : string
-- Name of requested form.
--
-- row : ModSys.S_natural
-- New row for the top row of the form.
--
-- col : ModSys.S_natural
-- New column for the left column of the form.
--
-- EXIT -
--
-- Sage.SageError : ModSys.S_natural
-- Error status return (27 if it will not fit).
--
procedure DisableMouse; --* -- DisableMouse - Disable the mouse for use within SAGE. -- -- -- This procedure disables an installed mouse for use within -- SAGE. The mouse may be enabled when required using the -- "Display.EnableMouse" function. When disabled, the mouse does -- not appear nor is usable within SAGE forms. --
procedure DisplayBackground
(FormName : in string;
Default : in boolean);
--*
-- DisplayBackground - Display background form.
--
--
-- This routine loads and displays a form on the screen. The
-- routine does not wait for user input. The user must have
-- created the form with the form editor and have opened the data
-- base prior to this call. The user may optionally cause the
-- record buffers associated with a form to be initialized to
-- their default values.
--
-- CALLING SEQUENCE -
--
-- DisplayBackground (FormName, Default)
--
-- ENTRY -
--
-- FormName : string
-- The name of the form to be displayed.
--
-- Default : boolean
-- Flag indicating whether the default values should be set in record
-- buffers associated with this form.
--
-- EXIT -
--
-- Sage.SageError : ModSys.S_natural
-- An error flag indicating the result of the operation.
--
procedure DisplayBackgroundV
(FormName : in string;
Default : in boolean;
fieldBuffer : in out string;
recordSize : in ModSys.S_Natural;
recordNum : in ModSys.S_Natural;
variableRecord : in string;
variableField : in string);
--*
-- DisplayBackgroundV - Display a form.
--
--
-- This routine loads and displays a form on the screen. The
-- user must have created the form with the form editor and have
-- opened the data base prior to this call. The user may
-- optionally cause the record buffers associated with a form to
-- be initialized to their default values. This differs from the
-- normal "DisplayBackground" because of the defined variable
-- field. This is similar to 'DisplayFormV'.
--
-- This differs from the "DisplayFormV" procedure, since it only
-- displays the form along with highlighted areas updated from
-- the buffer and does not require user input before leaving.
--
-- NOTE: The fieldBuffer must be global to the package in which it
-- is declared.
--
-- CALLING SEQUENCE -
--
-- DisplayBackgroundV (FormName, Default, fieldBuffer, recordSize,
-- recordNum, variableRecord, variableField)
--
-- ENTRY -
--
-- FormName : string
-- The name of the form to be displayed.
--
-- Default : boolean
-- Flag indicating whether the default values should be set in the record
-- buffers associated with this form.
--
-- fieldBuffer : string
-- Array containing contents of variable definition fields on the form.
--
-- recordSize : ModSys.S_natural
-- The character size of each record in the fieldBuffer.
--
-- recordNum : ModSys.S_Natural
-- The number of records of size "recordSize" in the "fieldBuffer".
--
-- variableRecord : string
-- The record part of the variable field definition.
--
-- variableField : string
-- Name of the field(s) on the form to have their contents varied by the
-- contents of the fieldBuffer. This field must be a highlighted field.
--
-- EXIT -
--
-- Sage.SageError : ModSys.S_natural
-- An error flag indicating the result of the operation.
--
procedure DisplayError
(errorNum : in ModSys.S_Natural;
Bell : in boolean);
--*
-- DisplayError - Display a message.
--
--
-- This routine loads and displays a message associated with one
-- of the Sage.SageError values on the screen. The user may select
-- whether the bell is rung. A Sage.SageError of zero will not be
-- be displayed.
--
-- CALLING SEQUENCE -
--
-- DisplayError (errorNum, Bell)
--
-- ENTRY -
--
-- errorNum : ModSys.S_natural
-- The sage error message number (see Sage.SageError).
--
-- Bell : boolean
-- Flag indicating whether to ring the bell prior to the message.
--
procedure DisplayForm
(FormName : in string;
Relation : in string;
Field : in string;
Default : in boolean);
--*
-- DisplayForm - Display a form.
--
--
-- This routine loads and displays a form on the screen. The
-- user must have created the form with the form editor and have
-- opened the data base prior to this call. The user may
-- optionally cause the record buffers associated with a form to
-- be initialized to their default values.
--
-- CALLING SEQUENCE -
--
-- DisplayForm (FormName, Relation, Field, Default)
--
-- ENTRY -
--
-- FormName : string
-- The name of the form to be displayed.
--
-- Relation : string
-- The name of a relation on the form to position the cursor in. The
-- default is the top-most, left-most field on the form.
--
-- Field : string
-- Name of a field on the form to position the cursor in. This field
-- name may also contain an instruction to position the cursor in a
-- particular occurrence of a highlighted field by following the field
-- name with '/n', where n is the number of the occurrence. For example
-- "FldName/35"
-- or
-- "Stats[3]/24" (repeating field)
--
-- Default : boolean
-- Flag indicating whether the default values should be set in the record
-- buffers associated with this form. Default values can be typed into
-- one or more of the individual fields (display only and entry fields)
-- of the form as it is created. If set to TRUE, then any non-blank values
-- on the form will be used to first update the associated memory records
-- before the form is displayed. If these fields are entry fields and the
-- user changes them while the form is displayed, the values entered will
-- be the new default values the next time the form is displayed with
-- 'Default' set to TRUE. This parameter (Default) is rarely set to
-- TRUE, except for an occasional form when first displayed.
--
-- EXIT -
--
-- SageError : ModSys.S_natural
-- An error flag indicating the result of the operation.
--
-- EXAMPLE -
--
-- with Sage;
--
-- procedure Display_A_Form is
-- Begin
-- Sage.OpenSystem ("MYDATA.DFL",5,5,5000);
-- Display.DisplayForm ("MyForm","MyRel","Fld",FALSE);
-- Sage.CloseSystem;
-- end Display_A_Form;
--
procedure DisplayFormV
(FormName : in string;
Relation : in string;
Field : in string;
Default : in boolean;
fieldBuffer : in out string;
recordSize : in ModSys.S_Natural;
recordNum : in ModSys.S_Natural;
variableRecord : in string;
variableField : in string);
--*
-- DisplayFormV - Display a form.
--
--
-- This procedure loads and displays a form on the screen just as
-- the 'DisplayForm' procedure. It differs from this procedure
-- because it allows data to be loaded into the specified
-- highlighted field of the form instead of accepting the data
-- defined in that field with the original form. This procedure
-- requires input of an array for data to be used in the
-- highlighted fields of a form.
--
-- This procedure and the 'DisplayFormVIP' procedure cause the
-- forms displayed to be in VARIABLE INPUT ARRAY mode. In this
-- mode, the 'DefineVariableArray' procedure may be used to
-- define procedures to load up variable areas of any of the
-- forms which are tied to the first form specified (such as help
-- forms).
--
-- When the user is presented with a form with this option, the
-- PgUp, PgDn, up and down arrow keys are used to vary the
-- contents of the highlighted fields defined by the
-- 'variableRecord' and 'variableField' parameters. The data to
-- fill the fields is determined by the user supplied
-- 'fieldBuffer'.
--
-- Each record in the supplied buffer of data may be greater than
-- or equal to the length of the highlighted field in which it is
-- to be displayed. This procedure will use only that portion of
-- each record in the buffer that is required for display in the
-- associated highlighted field.
--
-- NOTE: The fieldBuffer must be global to the package in which it
-- is declared.
--
-- CALLING SEQUENCE -
--
-- DisplayFormV (FormName, Relation, Field, Default, fieldBuffer,
-- recordSize, recordNum, variableRecord, variableField)
--
-- ENTRY -
--
-- FormName : string
-- The name of the form to be displayed.
--
-- Relation : string
-- The name of a relation on the form in which to position the cursor.
-- The default is the top-most, left-most field on the form.
--
-- Field : string
-- Name of a field on the form in which to position the cursor. This
-- field name may also contain an instruction to position the cursor in
-- a particular occurrence of a highlighted field by following the field
-- name with '/n', where n is the number of the occurrence. For example
-- "FldName/35"
-- or
-- "Stats[3]/24" (repeating field)
--
-- Default : boolean
-- Flag indicating whether the default values should be set in the
-- record buffers associated with this form. Reference the documentation
-- for this parameter in the 'DisplayForm' procedure argument list.
--
-- fieldBuffer : string
-- Array containing contents of variable definition fields for the form.
--
-- recordSize : ModSys.S_natural
-- The character size of each record in the fieldBuffer.
--
-- recordNum : ModSys.S_Natural
-- The number of records of size "recordSize" in the "fieldBuffer".
--
-- variableRecord : String
-- The record part of the variable field definition.
--
-- variableField : String
-- Name of the field(s) on the form to have their contents varied by the
-- contents of the fieldBuffer. This must be a highlighted field.
--
-- EXIT -
--
-- SageError : ModSys.S_natural
-- An error flag indicating the result of the operation.
--
-- EXAMPLE -
--
-- with Sage;
--
-- procedure Display_A_Form is
-- values : string (1..24);
-- begin
-- Sage.OpenSystem ("MYDATA.DFL",5,5,5000);
-- values := "Name1 Name2 Name3 Name4";
-- Display.DisplayFormV ("MyForm","MyRel","Fld",FALSE,
-- values,6,4,"MyRel","Names");
-- Sage.CloseSystem;
-- end Display_A_Form;
--
procedure DisplayFormVIP
(FormName : in string;
Relation : in string;
Field : in string;
Default : in boolean;
v_Proc : in SageSpec.VProcType;
recordSize : in ModSys.S_Natural;
recordNum : in ModSys.S_Natural;
variableRecord : in string;
variableField : in string);
--*
-- DisplayFormVIP - Display form using var. input procedure.
--
--
-- This procedure loads and displays a form on the screen just as
-- the 'DisplayForm' procedure. It differs from this procedure
-- because it allows data to be loaded into the specified
-- highlighted field of the form instead of accepting the data
-- defined in that field with the original form.
--
-- Where the 'DisplayFormV' procedure requires input of an array,
-- this procedure allows specification of a procedure which is
-- used to acquire the data needed for the screen. This is an
-- advantage if the total array requires too much memory or is
-- too slow to acquire. The procedure supplied to
-- 'DisplayFormVIP' will only be asked to supply one page at a
-- time as the user requires it to be displayed.
--
-- This procedure and the 'DisplayFormV' procedure cause the
-- forms display to be in VARIABLE INPUT ARRAY mode. In this
-- mode, the 'DefineVariableArray' procedure may be used to
-- define procedures to load up variable areas of any of the
-- forms which are tied to the first form specified (such as help
-- forms).
--
-- When the user is presented with a form with this option, the
-- PgUp and PgDn keys are used to vary the contents of the
-- highlighted fields defined by the "variableRecord" and
-- "variableField" parameters. The data to fill the fields is
-- determined by the user supplied "vProc" procedure which
-- returns an address of the data to be shown on the screen
-- within the highlighted fields.
--
-- NOTE: The fieldBuffer must not only be global, but in the later
-- ALSYS compiler releases, it must be exported from another package.
-- The procedure used to fill the array can not be nested. See
-- the EXAMPLE section.
--
-- CALLING SEQUENCE -
--
-- DisplayFormVIP (FormName, Relation, Field, Default, ABC,
-- recordSize, recordNum, variableRecord, variableField)
--
-- ENTRY -
--
-- FormName : string
-- The name of the form to be displayed.
--
-- Relation : string
-- The name of a relation on the form to position the cursor in.
-- The default is the top-most, left-most field on the form.
--
-- Field : string
-- Name of a field on the form to position the cursor in. This field
-- name may also contain an instruction to position the cursor in a
-- particular occurrence of a highlighted field by following the field
-- name with '/n', where n is the number of the occurrence. For example
-- "FldName/35"
-- or
-- "Stats[3]/24" (repeating field)
--
-- Default : boolean
-- Flag indicating whether the default values should be set in the record
-- buffers associated with this form. Reference the documentation for
-- this parameter in the 'DisplayForm' procedure argument list.
--
-- v_Proc : SageSpec.VProcType
-- Procedure which returns the address of the data to be shown on the
-- form.
--
-- recordSize : ModSys.S_natural
-- The character size of each record in the fieldBuffer.
--
-- recordNum : ModSys.S_Natural
-- The number of records of size "recordSize" to be displayed.
--
-- variableRecord : String
-- The record part of the variable field definition.
--
-- variableField : String
-- Name of the field(s) on the form to have their contents varied by the
-- contents of the fieldBuffer. This must be a highlighted field.
--
-- EXIT -
--
-- SageError : ModSys.S_natural
-- An error flag indicating the result of the operation.
--
-- EXAMPLE -
--
-- package Extra is
-- buf : string (1..100);
-- end Extra;
--
-- with Extra;
-- with Display;
-- with Sage;
-- with Calls;
-- with SYSTEM;
-- with ModSys;
--
-- procedure Test is
--
--
-- procedure MyDataLoad
-- (recNum : in ModSys.S_Natural;
-- recNeed : in ModSys.S_Natural;
-- bLoc : in out System.Address) is
-- begin
-- -- this procedure loads the 'buf' string with data
-- bLoc := Extra.buf'address;
-- end MyDataLoad;
--
-- function Picture_Load is new Calls.D_Check (MyDataLoad);
--
-- begin
-- Sage.OpenSystem ("MYDATA.DFL",5,5,5000);
-- Display.DisplayFormVIP ("TestForm", "RelName", "FldName", FALSE,
-- Picture_Load, 10, 1000, "RelName", "VarField");
-- Sage.CloseSystem;
-- end Test;
--
procedure DisplayMessage
(Message : in string;
Bell : in boolean);
--*
-- DisplayMessage - Display a message.
--
--
-- This routine loads and displays a message on the last line of
-- the screen. The user may select whether the bell is rung.
--
-- CALLING SEQUENCE -
--
-- DisplayMessage (Message, Bell)
--
-- ENTRY -
--
-- Message : string
-- The message to be displayed.
--
-- Bell : boolean
-- Flag indicating whether to ring the bell prior to the message.
--
function EnableMouse return boolean; --* -- EnableMouse - Enable the use of the mouse in SAGE. -- -- -- This procedure enables the use of the mouse in SAGE forms. -- If the mouse has not been initialized, it is done -- at this point. If it has already been initialized, it makes -- it available within SAGE display procedures. To use a mouse -- within SAGE, a mouse driver must have already been installed -- during or after boot up of your system. -- -- The "Display.DisableMouse" procedure deactivates the mouse for -- use within SAGE. -- -- CALLING SEQUENCE - -- -- m := EnableMouse; -- -- EXIT - -- -- m : boolean -- The mouse was enabled (TRUE), or a mouse and driver is -- not detected nor available (FALSE); --
procedure ForceFieldCheck
(autoCheck : in boolean);
--*
-- ForceFieldCheck - Force check on form fields.
--
--
-- This procedure causes the system to check the contents of every
-- field on a form when leaving that field regardless of whether
-- any changes have been made or not. The default when Sage is
-- first entered is FALSE (fields are only checked if a change
-- is made). This procedure is often useful for various functions
-- involved using the 'CheckLib.FieldCheck' procedure.
--
-- CALLING SEQUENCE -
--
-- ForceFieldCheck (autoCheck)
--
-- ENTRY -
--
-- autoCheck : boolean
-- Check each field of form as user attempts to leave that field (TRUE)
-- or check the contents of the field only if changes were made (FALSE).
--
procedure ForcedHelpReturn
(forceReturn : in boolean);
--*
-- ForcedHelpReturn - Force exit key(s) to return from help form.
--
--
-- This procedure causes an exit key to always return from a current
-- help form to the form which invoked it. The default for this
-- is FALSE. With this default, an exit key will instead invoke a
-- further help form under the following conditions -
--
-- 1) You are currently in a help form
-- 2) You are currently in a highlighted field of that help form
-- 3) A further help form is defined for the current field
--
-- When all of these conditions are met, an exit key acts just like
-- the help key. To override this, the ForcedHelpReturn procedure
-- may be called setting 'forceReturn' to TRUE.
--
-- CALLING SEQUENCE -
--
-- ForcedHelpReturn (forceReturn)
--
procedure FormFieldOverflow
(overFlow : in boolean);
--*
-- FormFieldOverflow - Turn field entry overflow ON or OFF.
--
--
-- This procedure allows the turning ON or OFF of the field entry
-- overflow (default is ON). This is the property of a field on
-- a form where the cursor will automatically be positioned at
-- the beginning of the following field after the last character
-- of the current field is typed in. If this is turned OFF, then
-- the cursor remains at the last character position of the
-- current field regardless of how many characters are typed into
-- that position until one of the movement keys (arrow, tab,
-- etc.) are pressed.
--
-- CALLING SEQUENCE -
--
-- FormFieldOverflow (overFlow)
--
-- ENTRY -
--
-- overFlow : boolean
-- Overflow option ON (TRUE) or OFF (FALSE).
--
procedure GetColorMode
(colorMode : in out ModSys.S_Natural);
--*
-- GetColorMode - Get the current color mode.
--
--
-- This procedure retrieves the current color status.
-- One of three status modes apply -
--
-- 0 - Color
-- 1 - Interpreted black and white (from the original color)
-- 2 - Fixed black and white (fields white, background black)
--
-- If using a monochrome adapter card, only options 1 and 2 are
-- available.
--
-- CALLING SEQUENCE -
--
-- GetColorMode (colorMode)
--
-- EXIT -
--
-- colorMode : ModSys.S_natural
-- The current mode in which the system operates. (0..2)
--
function KeyFunctionNumber
(c1 : in character;
c2 : in character) return ModSys.S_Natural;
--*
-- KeyFunctionNumber - Return function # of keyboard char.
--
--
-- This procedure returns the defined function number of the
-- given set of keyboard characters.
--
-- CALLING SEQUENCE -
--
-- n := KeyFunctionNumber (c1, c2)
--
-- ENTRY -
--
-- c1 : character
-- The first character used to define the specified function.
--
-- c2 : character
-- The second character of the pair if the first is ASCIIX.nul.
--
-- EXIT -
--
-- n : ModSys.S_Natural
-- Function number associated with the given characters
--
-- SAGE
-- No. function Description Default Key(s)
-- ----- ------------- ------------------------------- --------------------
-- 0 no function number found
-- 1 forward move cursor forward 1 position right arrow
-- 2 backward move cursor back 1 position left arrow/backspace
-- 3 up move cursor up 1 line up arrow
-- 4 down move cursor down 1 line down arrow
-- 5 tab tab to next entry field tab
-- 6 backtab back tab to previous field shift/tab
-- 7 restore restore field to original value Ctrl/R
-- 8 helpexit exit to associated help form F1
-- 9 home go to first field on form Home
-- 10 exit leave form Enter
-- 11 clearall clear all fields on form Ctrl/Home
-- 12 clearfield clear field from cursor Ctrl/End
-- 13 bw toggle between B&W/color Ctrl/B
-- 14 help user help for key functions Alt/H
-- 15 insert insert mode Ins
-- 16 delete delete a character Del
-- 17 copyscreen copy screen to file SCREEN.CPY Ctrl/K
-- 18 pagedown variable field page down PgDn
-- 19 pageup variable field page up PgUp
-- 20 helpabort exit help form F10
-- 21-30 exit1-exit10 special exit functions [programmer-defined]
-- 31 firstpage variable field first page Ctrl/PgUp
-- 32 lastpage variable field last page Ctrl/PgDn
-- 33 genhelpexit exit to general help form [programmer-defined]
-- 34 fieldInfo form/relation/field info Ctrl/F
-- 36 autoHELP toggle auto helps on and off Alt/A
-- 37 haltForms exit all stacked forms [programmer-defined]
-- 38 userHelp invoke special user help [programmer-defined]
-- 39 exitAndReset exit form & reset to prior values [programmer-defined]
-- 41-60 exit11-exit30 special exit functions [programmer-defined]
--
-- EXAMPLE -
--
-- functionNum : ModSys.S_Natural;
--
-- begin
-- functionNum := Display.KeyFunctionNumber (character'val(27),
-- character'val(0));
--
function LastExitChar return character; --* -- LastExitChar - Return character last used to exit form. -- -- -- This procedure returns the last exit character used to exit a -- form. The valid exit characters are defined by the exit -- character range of the current keyboard. If an exit character -- is used to terminate a form, then the "Display.LastExitFunction" -- function value is irrelevant and will be returned as 0. -- -- CALLING SEQUENCE - -- -- c := LastExitChar; -- -- EXIT - -- -- c : character -- Character used to exit the last form. This will be in the exit -- character range defined for the current keyboard set. If an exit -- character was not used, this value will be returned as an ASCIIX.nul. --
function LastExitFunction return ModSys.S_Natural;
--*
-- LastExitFunction - Return function # last used to exit form.
--
--
-- This procedure returns the function number (see the
-- 'DefineFunctionKey' procedure) last used to exit a form.
--
-- CALLING SEQUENCE -
--
-- k := LastExitFunction;
--
-- EXIT -
--
-- k : ModSys.S_natural
-- SAGE function number of key last used to exit form. Of the function
-- keys possible in a form, the following are commonly used to exit -
--
-- 10 - normal exit
-- 21 - special exit 1 through 30 - special exit 10
-- 41 - special exit 11 through 60 - special exit 30
--
-- EXAMPLE -
--
-- begin
-- -- define the special exit 1 key to be invoked by F1
--
-- Display.DefineFunctionKey (21,character'val(0),character'val(59));
--
-- -- define the special exit 2 key to be invoked by F2
--
-- Display.DefineFunctionKey (22,character'val(0),character'val(60));
--
-- Display.DisplayForm ("FormName","RelName","FldName",false);
--
-- -- evaluate which key was used to terminate the form
--
-- if (Display.LastExitFunction = 21) then
-- -- special operation matching the execution of the F1 key
-- elsif (Display.LastExitFunction = 22) then
-- -- special operation matching the execution of the F2 key
-- elsif (Display.LastExitFunction = 10) then
-- -- processing of normal form exit
-- end if;
--
procedure RefreshCheckScreen
(refreshOn : in boolean);
--*
-- RefreshCheckScreen - Refresh fields after FieldCheck.
--
--
-- This procedure allows the refresh flag to be set or reset.
-- This flag causes the fields of the current form to be
-- refreshed (displayed) after the user supplied defined field
-- checking procedure is called.
--
-- If using autohelp forms, this should be set to refreshOn=FALSE
-- to prevent the refresh from overwriting and thus covering up
-- the autohelp form which may be within the current form space.
--
-- If performing operations within a 'CheckLib.FieldCheck' procedure,
-- one or more fields other than the current field may have
-- changed values. When refreshOn=TRUE, all of the fields of
-- the form are update with the new values immediately upon
-- leaving 'CheckLib.FieldCheck'.
--
-- By default, the fields are refreshed (refreshOn = TRUE).
--
-- CALLING SEQUENCE -
--
-- RefreshCheckScreen (refreshOn)
--
-- ENTRY -
--
-- refreshOn : boolean
-- Refresh all of the fields after the user supplied field check
-- procedure is called (see Checklib). Default condition is TRUE.
--
procedure ResetForm
(FormName : in string);
--*
-- ResetForm - Reload form from schema file.
--
--
-- This procedure resets the indicated form by reading in the
-- original definition from the .DFL file.
--
-- CALLING SEQUENCE -
--
-- ResetForm (formName)
--
-- ENTRY -
--
-- formName : string
-- Name of form to be reset.
--
procedure RestoreKeyDefinitions
(keyTable : in SageSpec.KeyboardDef);
--*
-- RestoreKeyDefinitions - Restore saved keyboard definition.
--
--
-- This procedure restores saved keyboard definition settings
-- which have been saved using the 'SaveKeyDefinitions'.
--
-- CALLING SEQUENCE -
--
-- RestoreKeyDefinitions (keyTable);
--
-- ENTRY -
--
-- keyTable : SageSpec.KeyboardDef
-- Table of keyboard definitions (see Display.SaveKeyDefinitions).
--
-- EXAMPLE -
--
-- with Display;
-- procedure Test is
-- keys : SageSpec.KeyboardDef;
-- begin
-- Display.SaveKeyDefinitions (keys);
-- Display.RestoreKeyDefinitions (keys);
--
procedure RestoreScreen
(screenNumber : in ModSys.S_Natural);
--*
-- RestoreScreen - Restore a saved screen.
--
--
-- This procedure restores a screen which was previously saved
-- and referenced by an assigned number using "SaveScreen". If
-- the aging scheme for Sage has caused the requested screen to
-- be released, it cannot be restored. (note the explanation
-- for the "SaveScreen" procedure)
--
-- CALLING SEQUENCE -
--
-- RestoreScreen (screenNumber)
--
-- ENTRY -
--
-- screenNumber : ModSys.S_natural
-- Number of screen to restore.
--
-- EXAMPLE -
--
-- begin
-- Display.DisplayBackground ("form1",FALSE);
-- Display.DisplayBackground ("form2",FALSE);
-- Display.DisplayBackground ("form3",FALSE);
-- Display.SaveScreen (1);
-- Display.DisplayForm ("form4","MyRel","Field1",FALSE);
-- Display.RestoreScreen (1);
--
procedure SaveKeyDefinitions
(keyTable : out SageSpec.KeyboardDef);
--*
-- SaveKeyDefinitions - Save current keyboard definition.
--
--
-- This procedure saves the current keyboard definition settings
-- for possible restoration using the 'restoreKeyDefinitions'
-- procedure.
--
-- CALLING SEQUENCE -
--
-- SaveKeyDefinitions (keyTable);
--
-- EXIT -
--
-- keyTable : SageSpec.KeyboardDef
-- Current table of keyboard definitions (see Display.DefineFunctionKey).
--
-- EXAMPLE -
--
-- with Display;
-- procedure Test is
-- keys : SageSpec.KeyboardDef;
-- begin
-- Display.SaveKeyDefinitions (keys);
-- Display.RestoreKeyDefinitions (keys);
--
procedure SaveScreen
(screenNumber : in ModSys.S_Natural);
--*
-- SaveScreen - Save the current screen.
--
--
-- This procedure saves the contents of the currently displayed screen
-- and references it by the assigned number. This screen may be
-- restored later using the "RestoreScreen" function. Multiple
-- screens may be saved for later retrieval.
--
-- A screen may be stored in one of two ways. If the 'screenNumber'
-- is less than 100, then the screen may be aged out as are the normal
-- forms. For this reason, the aging scheme for forms may cause
-- screens to be released from memory if the number of forms called
-- upon to be displayed after the "SaveScreen" execution reaches the
-- number defined as a maximum when "OpenSystem" (the "MaxScreens"
-- argument) was first called. After a saved screen is aged and
-- released from memory, it can no longer be restored using
-- "RestoreScreen".
--
-- If the 'screenNumber' if greater than or equal to 100, then the
-- screen is saved until it is restored. This takes up one form
-- space for each screen saved. To successfully display a form, at
-- least one form space must be left after this kind of permanent
-- screen saving.
--
-- CALLING SEQUENCE -
--
-- SaveScreen (screenNumber)
--
-- ENTRY -
--
-- screenNumber : ModSys.S_natural
-- Number to assign to the saved screen. If this number is
-- less than 100 (1..99), then the screen may be aged out if
-- a number of forms are displayed before the 'RestoreScreen'
-- is called. If the number is 100..n, then the screen will
-- persist until 'RestoreScreen' is called.
--
-- EXAMPLE -
--
-- begin
-- Display.DisplayBackground ("form1",FALSE);
-- Display.DisplayBackground ("form2",FALSE);
-- Display.DisplayBackground ("form3",FALSE);
-- Display.SaveScreen (1);
-- Display.DisplayForm ("form4","MyRel","Field1",FALSE);
-- Display.RestoreScreen (1);
--
procedure ScrollEnumerationList
(scrollOptionOn : in boolean);
--*
-- ScrollEnumerationList - Allow enumerated list scrolling.
--
--
-- This option allows the user to scroll through the values
-- of the enumeration list if in an entry field for an
-- enumerated field by using the up and down functions (3 and
-- 4) which are normally the up and down arrow keys.
--
-- By default, this function is set to FALSE (arrow keys do
-- not scroll through the enumeration list).
--
-- CALLING SEQUENCE -
--
-- ScrollEnumerationList (scrollOptionOn)
--
-- ENTRY -
--
-- scrollOptionOn : boolean
-- The up and down keys scroll through the enumeration list
-- (TRUE).
--
procedure ScrollForm
(outerForm : in string;
innerEntry : in string;
innerDisplay : in string;
cursorPos : in out ModSys.S_Natural;
TotalRecords : in ModSys.S_Natural;
RecToFormProc : in RecToFormProcType;
FormToRecProc : in FormToRecProcType);
--*
-- ScrollForm - Variable scroll of multiple entry forms.
--
--
-- This procedure displays and allows scrolling through multiple
-- copies of an entry form. Two forms are requested. The outer
-- form is shown as a background form. The inner form is repeated
-- from 1..n times depending upon the invisible space defined in
-- the outer form. Both an inner form into which data is entered
-- and an inner form that is displayed may be provided by the user.
-- This allows the current form (of the 1..n total inner forms) to
-- be given a different appearance and more and/or different
-- fields.
--
-- If enough width is allowed for more than one column, it is used.
-- As noted, the outer form should have invisible space defined
-- within it to designate where the inner form is scrolled. This
-- need not be contiguous space, but each invisible area must be at
-- least large enough to contain an inner form.
--
-- This procedure uses special exits 22..30 (key functions 52..60)
-- for its processes. Any other exits may be defined using
-- 'DefineFunctionKey' before 'ScrollForm' is executed. ANY KEYBOARD
-- SETTINGS WHICH WERE DEFINED BEFORE ENTRANCE INTO 'ScrollForm' WILL
-- STILL BE DEFINED UPON LEAVING THIS procedure.
--
-- The up and down arrow keys are redefined within 'ScrollForm' to act
-- in a special way. In normal operation, they will cause the cursor
-- to move from one field to another within the same entry form IF
-- THE FIELDS LINE UP OVER EACH OTHER. Otherwise, these arrow keys
-- will move the cursor from one entry form to the other. This will
-- also be the case if the cursor is resident in a field at the bottom
-- of the entry form and the down arrow is pressed. The reverse
-- condition is true for the up arrow. There are two special exit
-- functions (special exits 25 and 26 corresponding to functions 55 and
-- 56) which always cause the cursor to move between entry forms when
-- pressed. These are not normally defined, but may be predefined by
-- the user. If defined with the up and down arrows (against function
-- 55 and 56 respectively), then this type of up and down movement will
-- override the normal operation of the up and down arrows as previously
-- described.
--
-- Special Exits used by ScrollForm
--
-- Function No. Name Des
-- ------------ ----------- ----------------------------
-- 52 exit22 Optionally user defined - search key
-- 53 exit23 Predefined motion
-- 54 exit24 Predefined motion
-- 55 exit25 Optionally user defined - up 1 form
-- 56 exit26 Optionally user defined - down 1 form
-- 57 exit27 Predefined motion
-- 58 exit28 Predefined motion
-- 59 exit29 Predefined motion
-- 60 exit30 Predefined motion
--
-- procedure RecordToForm
-- (recordNumber : in out ModSys.S_Natural;
-- entryForm : in boolean;
-- searchLine : in out string);
--
-- procedure FormToRecord
-- (recordNumber : in out ModSys.S_Natural;
-- fieldsChanged : in boolean;
-- refreshForm : in out boolean;
-- exitTheProc : in out boolean;
-- totalRecords : in out ModSys.S_Natural);
--
-- CALLING SEQUENCE -
--
-- Display.ScrollForm (outerForm, innerEntry, innerDisplay,
-- cursorPos, totalRecords, RecToFormProc,
-- FormToRecProc);
--
-- ENTRY -
--
-- outerForm : string
-- Name of form which defines the outer mask for the display.
--
-- innerEntry : string
-- Name of the form in which the cursor will reside for data entry
-- purposes and while cursoring through the list of entries. This form
-- should have the same size and shape as the 'innerDisplay' form.
--
-- innerDisplay : string
-- Name of the form in which data will be displayed. This form will
-- appear within the 'outerForm' from 1..n times depending on the space
-- provided in the outer form.
--
-- cursorPos : ModSys.S_Natural
-- Record number on which the cursor is requested to reside when the
-- display is first shown (1..n). If set to zero (0), the display will
-- be positioned in the same way it was when it was last terminated.
--
-- totalRecords : ModSys.S_Natural
-- Total number of records through which 'ScrollForm' will be permitted
-- to scroll.
--
-- RecordToForm : RecToFormProcType
-- Procedure which will be called when the memory record information for a
-- record is to be located so that it can be displayed in the current
-- inner form. This procedure acts both as a method to load a record and
-- to search for a record. If 'recordNumber' is non-zero, then a specific
-- record is required by 'ScrollForm' and must be supplied. If
-- 'recordNumber' is zero (0), then one of two search conditions exists -
--
-- 1) No entry or highlight fields exist on the 'innerEntry' form and a
-- key other than a motion key was pressed. This causes 'searchLine'
-- to be loaded with the character pressed. 'searchLine' is then
-- supplied to you for searching purposes.
--
-- 2) Key function number 52 (exit22) has been defined and was pressed by
-- the user, indicating that the user wishes to search for something.
-- The user is on the innerEntry form, and Type 1 - Display/Entry fields
-- are defined on that form. In case 1 above, the user indicated a
-- desire to search by simply typing in what he sought. But if the form
-- has entry fields defined on it, this won't work. ScrollForm must
-- have some method of notifying the programmer that the user wants
-- to search. Hence exit22.
--
-- FormToRecord : FormToRecProcType
-- Procedure which will be called each time an inner entry form is
-- exited. This may be when scrolling from one record to another using
-- the arrow or paging keys, or when an exit key is pressed. If the
-- change flag ('fieldsChanged') is set, you may update the changed data
-- (ReWriteRecord, etc.) in this procedure. An example is
--
-- EXIT -
--
-- cursorPos : ModSys.S_Natural
-- Record number on which cursor was located when procedure was terminated.
--
-- EXAMPLE -
--
-- with StringsX;
-- with Sage;
-- with Display;
-- with StringsX;
--
-- package MyPack is
--
-- procedure RecordToForm
-- (recNum : in out ModSys.S_Natural;
-- entryForm : in boolean;
-- searchString : in out string) is
-- begin
--
-- -- A record has been requested. Read it.
-- if (recNum > 0) then
-- Sage.ReadRecordN ("SAMPLE","KEYFIELD",recNum);
--
-- -- A search key has been pressed. Find a match and return.
-- elsif (StringsX.Length(searchString) > 0) then
-- Sage.ReadRecordA ("SAMPLE","KEYFIELD",Sage.GE,searchString);
-- if (Sage.SageError = SageErrs.OpOk) then
-- Sage.GetKeyPosition ("SAMPLE","KEYFIELD",recNum);
-- else
-- recNum := 0;
-- StringsX.NulFill ("",searchString);
-- end if;
-- end if;
-- end RecordToForm;
--
-- procedure FormToRecord
-- (recNum : in out ModSys.S_Natural;
-- changed : in boolean;
-- refresh : in out boolean;
-- exitProc : in out boolean;
-- recTot : in out ModSys.S_Natural) is
-- begin
-- if (changed) then
-- Sage.ReWriteRecord ("SAMPLE");
-- refresh := TRUE;
-- end if;
-- end FormToRecord;
--
--
-- procedure Sample is
--
-- recPos : ModSys.S_Natural;
-- recTot : ModSys.S_Natural;
--
--
-- begin
-- Sage.OpenSystem ("SAMPLE.DFL",3,3,5000);
-- Sage.OpenRelation ("SAMPLE",TRUE);
--
-- recPos := 1;
-- recTot := Sage.TotalRecords("SAMPLE");
-- Display.ScrollForm ("OuterF", "InnerE", "InnerD", recPos, recTot,
-- RecordToForm'access, FormToRecord'access);
--
-- Sage.CloseRelation ("SAMPLE");
-- Sage.CloseSystem;
-- end Sample;
--
-- end MyPack;
--
procedure ScrollFormBackground
(outerForm : in string;
innerDisplay : in string;
TotalRecords : in ModSys.S_Natural;
RecToFormProc : in RecToFormProcType);
--*
-- ScrollFormBackground - Background display version of ScrollForm.
--
function ScrollFormQueueSize return ModSys.S_Natural;
--*
-- ScrollFormQueueSize - Return inner forms not yet displayed.
--
--
-- This procedure returns the number of inner forms yet to be displayed
-- with associated requested data in the current request queue of
-- ScrollForm. This is useful when using MultSage to read in the data
-- and some form of lock such as ExclusiveWriteLockRelation is used to
-- speed up the process of paging within ScrollForm. When the queue
-- size returned is greater than zero (0), then ScrollForm will
-- immediately request information for n records (n = queue size)
-- before any user intervention is allowed.
--
-- CALLING SEQUENCE -
--
-- s := ScrollFormQueueSize;
--
-- EXIT -
--
-- s : ModSys.S_natural
-- Number of inner form requests remaining in the ScrollForm queue. If
-- zero (0), the current form was the last one and no more remain.
--
-- EXAMPLE -
--
-- with StringsX;
-- with MultSage;
-- with Display;
-- with StringsX;
--
-- procedure Sample is
--
-- recPos : ModSys.S_Natural;
-- recTot : ModSys.S_Natural;
-- xLocked : boolean := false;
--
-- procedure RecordToForm
-- (recNum : in out ModSys.S_Natural;
-- entryForm : in boolean;
-- searchString : in out string) is
-- begin
--
-- if (recNum > 0) then
--
-- -- Exclusively lock the relation if more records will be
-- -- immediately requested after the current one.
--
-- if (Display.ScrollFormQueueSize > 0) and then not xLocked then
-- MultSage.ExclusiveWriteLockRelation ("SAMPLE",300);
-- xLocked := (Sage.SageError = SageErrs.OpOk);
-- end if;
--
-- -- Read the requested record.
--
-- MultSage.ReadRecordN ("SAMPLE","KEYFIELD",recNum);
--
-- -- Unlock the relation if this record is the last one in a
-- -- series and the relation has been exclusively locked.
--
-- if (Display.ScrollFormQueueSize = 0) and then xLocked then
-- MultSage.ExclusiveUnlockRelation ("SAMPLE");
-- xLocked := false;
-- end if;
--
-- end if;
-- end RecordToForm;
--
-- procedure FormToRecord
-- (recNum : in out ModSys.S_Natural;
-- changed : in boolean;
-- refresh : in out boolean;
-- exitProc : in out boolean;
-- recTot : in out ModSys.S_Natural) is
-- begin
-- null;
-- end FormToRecord;
--
-- procedure MyScroll is new Display.ScrollForm
-- (RecordToForm,FormToRecord);
--
-- begin
-- MultSage.OpenSystem ("SAMPLE.DFL",3,3,5000);
-- MultSage.OpenRelation ("SAMPLE",TRUE);
--
-- recPos := 1;
-- recTot := MultSage.TotalRecords("SAMPLE");
-- MyScroll ("OuterF","InnerE","InnerD",recPos,recTot);
--
-- MultSage.CloseRelation ("SAMPLE");
-- MultSage.CloseSystem;
-- end Sample;
--
procedure SelectDefaultKeyboard; --* -- SelectDefaultKeyboard - Set to default keyboard. -- -- -- This procedure resets the keyboard to the default. This -- default should have been defined within the current -- data dictionary (.DFL) file. -- -- CALLING SEQUENCE - -- -- SelectDefaultKeyboard --
procedure SelectKeyboard
(keyboardName : in string);
--*
-- SelectKeyboard - Select named keyboard set.
--
--
-- This procedure allows the selection of a predefined keyboard
-- set. If the set is not defined (available), then a SageError
-- of 61 is returned.
--
-- CALLING SEQUENCE -
--
-- SelectKeyboard (keyboardName)
--
-- ENTRY -
--
-- keyboardName : string
-- The name of the keyboard to be selected.
--
-- EXIT -
--
-- Sage.SageError : ModSys.S_natural
-- An error flag indicating the result of the operation.
--
procedure SetColorMode
(colorMode : in ModSys.S_Natural);
--*
-- SetColorMode - Set current color mode.
--
--
-- This procedure allows the setting of the current color status.
-- One of three status modes apply -
--
-- 0 - Color
-- 1 - Interpreted black and white (from the original color)
-- 2 - Fixed black and white (fields white, background black)
--
-- If using a monochrome adapter card, only options 1 and 2 are
-- available.
--
-- CALLING SEQUENCE -
--
-- SetColorMode (colorMode)
--
-- ENTRY -
--
-- colorMode : ModSys.S_natural
-- The mode in which the system should operate. (0..2)
--
procedure SetMessageColor
(messageColor : in ModSys.S_Integer);
--*
-- SetMessageColor - Set color of message.
--
--
-- This procedure sets the color of the standard message which is
-- displayed at the bottom of the screen.
--
-- CALLING SEQUENCE -
--
-- SetMessageColor (messageColor)
--
-- ENTRY -
--
-- messageColor : ModSys.S_integer
-- Appearance of standard messages shown at the bottom of the screen.
-- 0..255 or -1 to reset to the default appearance.
--
-- A list of the message colors follows -
--
-- msg. col. foreground background
-- --------- ---------- ----------
-- 0 black black
-- 1 blue black
-- 2 green black
-- 3 cyan black
-- 4 red black
-- 5 magenta black
-- 6 brown black
-- 7 white black
-- 8 gray black
-- 9 light blue black
-- 10 light green black
-- 11 light cyan black
-- 12 light red black
-- 13 light magenta black (default)
-- 14 yellow black
-- 15 light white black
-- 16..31 (same as 0..15) blue
-- 32..47 (same as 0..15) green
-- 48..63 (same as 0..15) cyan
-- 64..79 (same as 0..15) red
-- 80..95 (same as 0..15) magenta
-- 96..111 (same as 0..15) brown
-- 112..127 (same as 0..15) white
-- 128..255 (same as 0..127 except blink foreground)
--
procedure UnloadForm
(FormName : in string);
--*
-- UnloadForm - Unload form from memory.
--
--
-- This procedure unloads the indicated form from the memory area.
--
-- CALLING SEQUENCE -
--
-- UnloadForm (formName)
--
-- ENTRY -
--
-- formName : string
-- Name of form to be unloaded.
--
procedure UnloadAllForms;
function VariableIndex return ModSys.S_Natural;
--*
-- VariableIndex - Return index to last var. form array.
--
--
-- When a user makes a selection and exits a V-type form, this procedure
-- returns the index within the array used by that 'DisplayFormV' or
-- 'DisplayFormVIP' procedure corresponding to the user selection. When
-- another 'DisplayFormV' call is made or a form using variable highlighted
-- fields is called within a help sequence, the variable index is updated to
-- reflect it and the old setting is lost. If a zero (0) is
-- returned, then none of the presented fields were selected by the user.
--
-- CALLING SEQUENCE -
--
-- i := VariableIndex
--
-- EXIT -
--
-- i : ModSys.S_Natural
-- Record number within the variable array used (1..n) or zero if
-- none was selected.
--
-- EXAMPLE -
--
-- i : ModSys.S_Natural;
--
-- begin
-- Sage.OpenSystem ("MYDATA.DFL",5,5,5000);
-- Display.DisplayFormVIP ("TestForm", "RelName", "FldName", FALSE,
-- Picture_Load, 10,1000, "RelName", "VarField");
-- i := Display.VariableIndex;
--
procedure SetMessageStyle
(MessageStyle : in MessageStyleType);
--*
-- SetMessageStyle - Sets the message style in SageTerms.
--
--
-- This procedure sets the message style for SageTerms. If
-- the setting is SageTermStyle then messages show on the 25th
-- screen line. If set to WindowsStyle they show up as a
-- separate dialog.
--
Send mail to
warren.merrill@inl.gov
with questions or comments about this web site.
Copyright © 1989-2006 Battelle Energy Alliance