RExL Version 2.11 A Rule-based Applications Development Environment From The Software Loft, Kiemar House, Shanakiel Road, Cork City, Ireland. Tel: [+353] 21-302511 Fax: [+353] 21-343562 Internet: softloft@iruccvax.ucc.ie Compuserve: 100042,1237 -- Part I -- The Main Manual -- _______ ____|__ | (R) --| | |------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals -----| | |--------------------- |___|___| MEMBER This program is produced by a member of the Association of Shareware Professionals (ASP). ASP wants to make sure that the shareware principle works for you. If you are unable to resolve a shareware-related problem with an ASP member by contacting the member directly, ASP may be able to help. The ASP Ombudsman can help you resolve a dispute or problem with an ASP member, but does not provide technical support for members' products. Please write to the ASP Ombudsman at 545 Grover Road, Muskegon, MI 49442- 9427 or send a Compuserve message via CompuServe Mail to ASP Ombudsman 70007,3536. o Information in this document is subject to change without notice and does not represent a commitment on the part of The Software Loft. The software described in this manual may be used and copied within the terms of the license agreement. Turbo C, Turbo Pascal and Sidekick are registered trademarks of Borland International. dBase III+ and dBase are registered trademarks of Ashton-Tate. (C) Copyright, The Software Loft, 1992. All rights reserved. If you have any difficulties, please contact us at the address above. Contents Chapter 1 Introduction 3 1.1 What is RExL . . . . . . . . . . . . . . 3 1.2 System requirements . . . . . . . . . . 4 1.3 Installation . . . . . . . . . . . . . . 4 1.4 Features . . . . . . . . . . . . . . . . 5 1.4.1 Editor . . . . . . . . . . . . . . 5 1.4.2 Runtime-Debugger . . . . . . . . . 6 1.4.3 Language . . . . . . . . . . . . . 6 1.5 The Manual . . . . . . . . . . . . . . . 7 Chapter 2 Language 9 2.1 Variables . . . . . . . . . . . . . . . 9 2.2 Constants . . . . . . . . . . . . . . 10 2.3 Arrays . . . . . . . . . . . . . . . . 11 2.4 Operators . . . . . . . . . . . . . . 12 2.4.1 Mathematical Operators . . . . . 12 2.4.2 Comparison Operators . . . . . . 14 2.5 Functions . . . . . . . . . . . . . . 14 2.6 Expressions . . . . . . . . . . . . . 16 2.7 Assignments . . . . . . . . . . . . . 18 2.8 Statements . . . . . . . . . . . . . . 19 2.9 Inference . . . . . . . . . . . . . . 19 2.10 Rules and Execution . . . . . . . . . 20 2.11 Subrules . . . . . . . . . . . . . . 21 2.12 Rule Modifiers . . . . . . . . . . . 22 2.12.1 BackTo . . . . . . . . . . . . . 23 2.12.2 Not . . . . . . . . . . . . . . 23 2.12.3 While . . . . . . . . . . . . . 23 2.12.4 Multi . . . . . . . . . . . . . 24 2.12.5 Single . . . . . . . . . . . . . 24 2.12.6 Zap . . . . . . . . . . . . . . 24 2.13 Other Modifiers . . . . . . . . . . . 24 Chapter 3 Quick Start 27 3.1 Introduction . . . . . . . . . . . . . 27 3.2 Creating an Application . . . . . . . 28 3.3 Running the Application . . . . . . . 29 3.4 Expanding the Application . . . . . . 30 i 3.5 Debugging the Application . . . . . . 32 Chapter 4 The Editor 35 4.1 Introduction . . . . . . . . . . . . . 35 4.2 Interface Conventions . . . . . . . . 36 4.3 Editor Basics . . . . . . . . . . . . 39 4.3.1 File menu . . . . . . . . . . . . 41 4.3.2 Edit menu . . . . . . . . . . . . 43 4.3.3 Run menu . . . . . . . . . . . . 43 4.3.4 Lists menu . . . . . . . . . . . 44 4.3.5 Options menu . . . . . . . . . . 46 4.3.6 Import menu . . . . . . . . . . . 47 4.4 Using the Editor . . . . . . . . . . . 49 4.4.1 Entering Statements . . . . . . . 50 4.4.2 Entering Rules . . . . . . . . . 51 4.4.3 Entering Screens . . . . . . . . 52 4.5 Editor Lists . . . . . . . . . . . . . 52 4.5.1 Reference List . . . . . . . . . 53 4.5.2 Rule List . . . . . . . . . . . . 53 4.5.3 Screen List . . . . . . . . . . . 53 4.5.4 Unused Rule List . . . . . . . . 54 4.5.5 Unused Screen List . . . . . . . 54 4.5.6 Variable List . . . . . . . . . . 54 4.5.7 Function List . . . . . . . . . . 55 4.6 Other Functions . . . . . . . . . . . 56 4.6.1 Graphic Rule Display . . . . . . 56 4.6.2 Miscellaneous keystrokes . . . . 57 4.6.2.1 Cut and paste . . . . . . . 57 4.6.2.2 Editing keys . . . . . . . . 57 4.6.2.3 Other keys . . . . . . . . . 58 Chapter 5 Screens in RExL 59 5.1 Introduction . . . . . . . . . . . . . 59 5.2 Fields . . . . . . . . . . . . . . . . 60 5.2.1 Introduction . . . . . . . . . . 60 5.2.1.1 Field Properties . . . . . . 60 5.2.2 Output Fields . . . . . . . . . . 61 5.2.3 Input Fields . . . . . . . . . . 61 5.2.4 Toggle List Fields . . . . . . . 61 5.2.5 Check Box Fields . . . . . . . . 62 5.2.6 Radio Button Fields . . . . . . . 62 5.2.7 Menu Fields . . . . . . . . . . . 63 5.3 Screen Types . . . . . . . . . . . . . 63 5.3.1 Dialog Screen . . . . . . . . . . 65 5.3.2 Display Screen . . . . . . . . . 65 5.3.3 Help Screen . . . . . . . . . . . 66 5.3.4 Menu Screen . . . . . . . . . . . 66 5.3.5 Print Screen . . . . . . . . . . 67 ii 5.3.6 Subscreens . . . . . . . . . . . 67 Chapter 6 Using the Screen Designer 69 6.1 Starting the Screen Designer . . . . . 69 6.2 Basic Design . . . . . . . . . . . . . 70 6.3 Fields in the Screen Designer . . . . 71 6.3.0.1 Output . . . . . . . . . . . 73 6.3.0.2 Input . . . . . . . . . . . 73 6.3.0.3 Toggle . . . . . . . . . . . 73 6.3.0.4 Check . . . . . . . . . . . 74 6.3.0.5 Radio . . . . . . . . . . . 74 6.3.0.6 Menu . . . . . . . . . . . . 74 6.4 Block Operations . . . . . . . . . . . 75 6.4.1 Block Painting . . . . . . . . . 75 6.4.2 Align . . . . . . . . . . . . . . 76 6.4.3 Box . . . . . . . . . . . . . . . 76 6.4.4 Delete . . . . . . . . . . . . . 77 6.4.5 Move . . . . . . . . . . . . . . 77 6.4.6 Copy . . . . . . . . . . . . . . 78 6.4.7 Fill . . . . . . . . . . . . . . 78 6.4.8 Save . . . . . . . . . . . . . . 79 6.4.9 Under shadow . . . . . . . . . . 79 6.5 Sub-screens . . . . . . . . . . . . . 79 6.6 Field control menu . . . . . . . . . . 80 6.6.0.1 Active color . . . . . . . . 81 6.6.0.2 Inactive color . . . . . . . 81 6.6.0.3 Delete . . . . . . . . . . . 82 6.6.0.4 Expression . . . . . . . . . 82 6.6.0.5 Recalc . . . . . . . . . . . 82 6.6.0.6 Justify . . . . . . . . . . 82 6.6.0.7 Width . . . . . . . . . . . 82 6.6.0.8 Necessary . . . . . . . . . 83 6.6.0.9 Precision . . . . . . . . . 83 6.6.0.10 Validation . . . . . . . . 83 6.7 Miscellaneous Functions . . . . . . . 83 6.7.0.1 Changing Field Types . . . . 83 6.7.0.2 Field Utility Keys . . . . . 84 6.7.0.3 Line Drawing . . . . . . . . 84 6.7.0.4 Other Editing Keys . . . . . 86 6.7.0.5 Lists in the Screen Designer . . . . . . . . . . 86 6.7.0.6 Miscellaneous Keys . . . . . 87 Chapter 7 The Runtime-Debugger 89 7.1 Introduction . . . . . . . . . . . . . 89 7.2 Debugger Basics . . . . . . . . . . . 89 7.2.1 File menu . . . . . . . . . . . . 91 7.2.2 Debug menu . . . . . . . . . . . 91 iii 7.2.3 Lists menu . . . . . . . . . . . 92 7.2.4 Options menu . . . . . . . . . . 94 7.3 Using the Debugger . . . . . . . . . . 95 7.3.1 Step . . . . . . . . . . . . . . 96 7.3.2 Trace . . . . . . . . . . . . . . 97 7.3.3 Watch . . . . . . . . . . . . . . 97 7.3.4 Expression Evaluate . . . . . . . 98 7.3.5 Animation . . . . . . . . . . . . 98 7.3.6 To Here . . . . . . . . . . . . . 99 7.4 Miscellaneous keystrokes . . . . . . . 99 7.5 Command Line Parameters . . . . . . . 100 iv Tables Table 2.1: Valid and Invalid Variable Names . .10 Table 2.2: Numeric and String Constants . . . .11 Table 2.3: Array Subscription . . . . . . . . .12 Table 2.4: RExL Math Operators . . . . . . . . .13 Table 2.5: Logical Operators . . . . . . . . . .14 Table 2.6: Comparison Operators . . . . . . . .14 Table 2.7: Function Families . . . . . . . . . .15 Table 2.8: Some Expressions . . . . . . . . . .16 Table 2.9: Operator Precedence . . . . . . . . .17 Table 2.10: Examples of Operator Precedence . .18 Table 2.11: Examples of Assignments . . . . . .19 Table 2.12: Rule Modifiers . . . . . . . . . . .23 Table 2.13: Other Modifiers . . . . . . . . . .25 Table 2.14: Expression Truth Values . . . . . .25 Table 4.1: ASCII Color Translation Table . . . .48 Table 4.2: Function Parameter Abbreviations . .55 Table 5.1: Screen Types . . . . . . . . . . . .64 Table 5.2: Valid Combinations of Screen and Field Type . . . . . . . . . . . . . . . .64 Table 6.1: Screen Designer Cursor Keys . . . . .71 Table 6.2: Valid Field Sizes . . . . . . . . . .72 Table 6.3: Valid Field Attributes . . . . . . .81 Table 6.4: Keys in Line Draw Mode . . . . . . .86 v - Main Manual. Page: 3 - Chapter 1 Introduction This chapter provides a brief introduction to RExL, its system requirements, installation and capabilities and quick signpost to the rest of the manual. 1.1 What is RExL RExL, short for Rule-base EXpert Language is a fourth generation language product for PC compatible computers which is based upon the `expert system' programming paradigm. It allows the applications developer to prototype applications rapidly and easily, while producing code which is easy to follow and understand. RExL comprises an editor for creating and modifying applications and a runtime module with incorporated debugger for testing and running the resulting application. RExL was developed with the following goals in mind: o Ease of use: Menus and pop-up lists are available times through hotkeys for experienced users, and via pulldown menus for those not so familiar with RExL. Online context-sensitive, cross referenced help is available at all times to the user. o Integrity: RExL was conceived as a single unit, with all features intimately connected together, unlike traditional languages where editors and debuggers are general purpose tools and not tailored for specific languages. o Power: RExL not only has a powerful internal language with 178 functions available but also has a fully integrated screen designer and dBase compatible database module. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 4 - 1.2 System requirements RExL will run on the IBM PS/2, PC/AT, PC/XT, PC, PC/Jr, and on IBM PC clones. The minimum requirements are: o 256 KB of memory, although RExL can use as much conventional DOS memory as is available. o PC-DOS 3.0 or greater or MS-DOS 3.0 or greater. o One high density 5.25" or one 720k 3.5" diskette drive, although a hard drive with at least 600k free is recommended. o An 80-column video card and monitor. o REXL.EXE, the editor and REXLRD.EXE, the runtime- debugger module. 1.3 Installation If you are installing the Shareware version, installation of RExL is accomplished easily. Copy the archive files REXLA211.ZIP and REXLB211.ZIP into a directory on your hard disk (we suggest "\REXL") and unzip the archive, using the commands: pkunzip -d rexla211 pkunzip -d rexlb211 The installation will proceed automatically and will require about 1.5Mb of disk space. If you are installing the full registered version, insert the first distribution disk in your disk drive, log onto it, issue the DOS command install and follow the prompts. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 5 - 1.4 Features The RExL package comes in three main parts: o The editor which is used for creating and modifying applications written in RExL, o The runtime-debugger module which is used to run and debug applications. o The supplementary utilities, stored in the second archive in the shareware version, which complete the suite of development tools. The next two sections provide a brief overview of both these modules. The final section in this chapter gives a quick introduction to RExL's internal language. 1.4.1 Editor RExL's editor uses the concept of `folding text' to make the programmer's job easier. In any computer language, applications are built up in a pyramidal manner, using procedures within procedures: this gives the program a two dimensional structure which has been ignored by traditional flat file editors. RExL on the other hand understands this structure and allows the programmer to access procedures immediately, without having to do searches or large cursor movements. Lists of all entities defined in your application are available at all times within the editor, and most entity lists have cross reference facilities. The screen designer is an integral part of the editor and features the following: o Block mark, copy, move, delete, color, fill and alignment, o Box and line drawing, o Subscreen manipulation, o IO fields : numeric input and output, character input and output, radio buttons, check boxes, toggle lists and menus, o Screen compression within single screen files. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 6 - The cross referenced help system is available at all times while within the editor and contains almost six thousand lines of context sensitive help. All RExL functions are fully explained in the help and come complete with examples of their use. 1.4.2 Runtime-Debugger RExL's debugger and runtime module feature line step, trace and instruction animation using industry standard keystrokes. A full watch facility and comprehensive expression evaluator can be used to check variables and expressions during execution of an application. As with the editor, all features are available via debugger hotkeys and pull down menus. As in the editor, on-the-fly macro definition, store and retrieval is also featured. 1.4.3 Language RExL's internal language has been designed to resemble BASIC. It supplies all the normal mathematical operators of division, multiplication, addition, subtraction, negation, exponentiation and logical OR, AND and NOT. The language has one hundred and seventy-eight functions which are grouped under the following headings: o Database: The integral database is dBase III compatible and supports the use of standard index files. There are forty functions controlling the database module. The number of data files and index files open concurrently is limited only by DOS. o Date-Time: There is a full set of date and time handling functions. These can use the three most common date and time formats of the USA, Europe and Japan. There are nineteen functions in this category. o DOS: The fourteen DOS interface functions perform the most commonly required procedures, such as file copy, rename, delete, directory maintenance and system identification. o Math: There are forty mathematical and financial functions (not including the math functions which operate on arrays and databases). The math functions cover all the standard trigonometric functions, as - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 7 - well as random number generation, boolean algebra and ASCII character manipulation. The financial functions cover the areas of loans and annuities. o Array handling: There are nine functions which operate on RExL arrays. Arrays may be numeric or string in type and can have up to three dimensions. o Miscellaneous: There are sixty-two miscellaneous functions which control character string manipulation, error handling, simple numeric and string screen IO and keyboard handling, binary and logical operations and arithmetic. The language itself is based upon the concept of rules, which are equivalent to procedures in more conventional programming languages. Rules are made up of logical blocks of lines, known as AND-blocks, which execute in much the same manner as Prolog predicates. The lines themselves within the rule can be built up of executable statements, in RExL's internal language, or be made up of other rules. Screens generated using the screen designer are accessed in much the same manner as rules. The screen designer allows numeric and character IO, dialog screen generation, online help and printer access. 1.5 The Manual Where keystrokes are specified, the shift, alt or ctrl segment is written first with the combination key second. For example, to call up language help, the keystroke is as follows: Press down the key and while it is down, press the key. This keystroke is written as . The plan of the manual is : o General introduction to RExL o General guide to RExL's language o Quick start guide o In-depth guide to the editor o In-depth guide to the screen designer (two chapters) - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 8 - o In-depth guide to the debugger o Appendices - Guide to Function Families - Database Programming - Function reference - Keystroke reference - Afterword It is recommended that at the very least, you should read the language guide and the quick start guide. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 9 - Chapter 2 Language RExL's language was designed to resemble BASIC, so that users who had experience in this language would have little difficulty in switching to RExL. This chapter will introduce all of the basic concepts which you'll need to understand before you can begin to program in RExL. If you have programmed before, then a quick read through this chapter should be adequate, since the concepts presented are common across most programming languages. 2.1 Variables A variable is a name which is used to refer to a location in memory which stores a retrievable value. In RExL, there are two types of variable: o Numeric variables which contain numeric information. These variables can range in absolute value from 2.225074x10^-308 to 9.7693x10^308 and can hold numbers accurate to about fifteen decimal digits of precision. o String variables which contain character information. These have a maximum length of eighty characters. RExL variable names follow the standard conventions for variable names in most languages. These are that they must consist of a letter followed by an unbroken sequence of letters, digits or the underscore character, _. Note that for compatibility with future RExL products, an underscore is not allowed as the initial letter of a variable name. To distinguish between string and numeric variables, all string variable names have a dollar sign, $, as the last letter in their name. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 10 - The following list gives some typical variable names: Table 2.1: Valid and Invalid Variable Names name$ String variable my_age Numeric variable 1st Invalid : initial character is not a letter my age Invalid : space included in the middle of the name co$t Invalid : characters after the dollar sign addr$$ Invalid : double dollar at end 2.2 Constants A constant is an invariable numeric or string value. Numeric constants are simply numbers such as 0, 10, 123.456 and so on. They have the same range of value as the numeric variables above. For large numbers above one million trillion, RExL uses the standard computer format scientific notation. This format is almost identical to that of scientific notation and consists of a mantissa which can be up to fifteen digits long and contains the significant digits of the number, expressed as a number between one and ten. The mantissa is followed by the letter E (or e, standing for exponent) followed by a plus or minus symbol followed by a number between 15 and 308, representing the power of ten with which the mantissa is to be multiplied. There are no spaces in between the different sections of the number and a plus sign is assumed if the plus or minus symbol is omitted. Thus the average distance from the sun to the earth can be expressed in this format as 5.8925E+12 = 5.8925x10^12 inches. String (or character) constants are simply lists of characters. They are delimited at either end by the double quotation mark ", and may contain any ASCII character except that of zero, used internally. The following table lists a few typical string and numeric constants. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 11 - Table 2.2: Numeric and String Constants 1e+6 Numeric value of one million 5e-3 Numeric value of five thousandths 1e+-376 Illegal: confusion over plus/minus and the exponent is greater than 308 "Hello" The string `Hello' "Whoops Illegal: no closing double quotation mark 2.3 Arrays Some applications require lists of string or numeric information. For example, the list of monthly sales figures for a single year would require a list of twelve numeric variables, one for each month. RExL supports the use of arrays of string and numeric variables to store this type of information. An individual number or string item in an array is known as an element of that array. Arrays more complex than simple lists are also possible, in fact arrays may have up to three dimensions specified. For example, if the sales figures for a single year for a number of different departments were stored, although they could be stored as above in a one dimensional list, it is more convenient to store them as a two dimensional list or array: one dimension to locate the month and one dimension to locate the department number. Similarly three dimensional arrays could be used to store the monthly sales figures for different departments across different years. Two dimensional arrays can be thought of as a (numeric or string type) grid with the dimensions specified relating to the rows and columns of the grid. Three dimensional arrays can be thought of as a stack of these grids. It is clearly immaterial to RExL whether the any particular dimension refers to the row number, column number or depth of a particular element, however, to keep things clear in your mind, you should adopt a standard method of reference. We suggest the convention that the first dimension is column number, the second is the row number and the third dimension is the depth. This convention is used elsewhere in RExL and conforms to the standard (x,y,z) notation used in Cartesian geometry. To reference a particular element in an array, RExL needs to know its position within the array. This is specified by placing the `co-ordinates' of the element of interest in - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 12 - square brackets immediately after the array's name. The co-ordinates of a particular element are known as the array element subscripts and are based at zero, meaning that the first element of an array is indexed by a subscript of zero, the second by a value of one and so on.(This behaviour is compatible with the C language and is adhered to throughout RExL where all co-ordinates, string indexes and so on are zero based.) In two and three dimensional arrays, the separate subscripts are separated by commas. Note that an array must by subscripted by the correct number of subscripts. The following table give a few examples of addressing individual elements of arrays. Table 2.3: Array Subscription name$[0] Returns first element in name$[] age[6] Returns seventh element in age[] sales[3,0] Returns the number in the first row of the fourth column of the two dimensional array sales[] By default, all arrays are dimensioned to ten elements. This can be changed through the variable dictionary, described in the chapter on the editor. When you are using three dimensional arrays, be aware that large amounts of memory are consumed. As a guide to determining the exact amount used, each element of a numeric array of any dimension uses eight bytes of storage. For string arrays, each element uses four bytes (when the application starts) and a further eighty-one bytes when an element is first accessed. This behaviour for string arrays helps to conserve memory if not all elements in an array are used, as is usually the case. 2.4 Operators 2.4.1 Mathematical Operators An operator is a symbol which performs some action upon an operand (or operands) and returns a value. The standard mathematical symbols + - x and / with which most people are familiar are supported in RExL, along with number of extra ones. They are listed in the following table: - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 13 - Table 2.4: RExL Math Operators * Multiplication ^ Exponentiation / Division & Logical AND + Addition | Logical OR - Subtraction ! Logical NOT Note that the minus sign can also be used to denote a unary minus, that is one which changes the sign of its immediate operand. The four operators in the right hand column may not be familiar to you. The first operator, the exponentiation operator a caret, ^, is used to raise the first operand to the power of the second. Thus, 2^2=4 and 3^2=9. The logical AND operator, the ampersand symbol &, returns the result of a logical AND of the both operands. This is equal to one if both operands are non zero, otherwise the result is zero. So, 1&1 gives 1 but 1&0 returns 0. The logical OR operator, the piping symbol |, returns the result of a logical OR of both operands. This is equal to one if either of the two operands are non zero, otherwise it is zero. So, 0|1 gives 1 but 0|0 gives 0. The final logical operator symbol, the exclamation mark !, performs a logical inversion of its single operand. This means that it will reverse the logical meaning of the value to which it is applied. Thus !1 returns 0 and !0 returns 1. When dealing with the logical operators &, | and !, it may help you to think of a value of zero meaning False and a non-zero value meaning True. Thus, !1 is equivalent to !True, giving False and 1&0 is equivalent to True & False giving False. The following table lists the results of the logical operations of Not, Or and And applied to a pair of True and False operands. These logical operators are sometimes referred to as boolean operators, after the Irish mathematician, George Boole, who developed the algebra of logic. A number of more complex logical operations are available as function calls, including exclusive-or, implication and equivalence. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 14 - Table 2.5: Logical Operators A B !A A&B A|B 0 0 1 0 0 0 1 1 0 1 1 0 0 0 1 1 1 0 1 1 2.4.2 Comparison Operators The final set of RExL symbols are the comparison operators, which are used to compare one string or number value with another value of the same type. There are six comparison operators which are listed below: Table 2.6: Comparison Operators = Test for equality > Test for greater than <> Test for inequality <= Test for less than or equal to < Test for less than >= Test for greater than or equal to These operators are defined for both string and numeric types. When applied to string type operands, RExL uses the ASCII character set to determine if one string is `less than' or `greater than' another. Refer to appendix F for an table of ASCII characters. 2.5 Functions A function is an in-built part of RExL's internal language which performs some action, or calculation on some values, and then returns a value of some specific type. Like variables, the type of the value they return is indicated by the presence or absence of a dollar sign. In general, the return type of a function is not related to its parameters, the value or values which the function operates upon. The process of using a function is generally referred to as calling that function. The values which are given (or passed) to the function are known as parameters. You are probably familiar with some functions already: the mathematical functions log, tan, cos and so forth, are functions (and available in RExL), since they are passed - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 15 - some value and return the value of the function at that particular point. Thus, the value of the tan function at pi radians evaluates as zero. This could be coded in RExL as tan(3.1416). Every RExL function uses a fixed number of parameters, generally of fixed type. For example, the math functions above require the use of numeric parameters since trying to find the logarithm of a string is meaningless. The DISPLAY() function will write a string on the screen to the current cursor location. This function takes only one parameter, a string. To write the string "Hello, world" on the screen, we could write a RExL line such as DISPLAY("Hello, world"). Passing arrays to functions is rather more complex: Because some functions taking arrays require arrays of a specific dimension, dummy subscripts must be passed in place of numeric ones (the dummy subscript used is the hash symbol, #). The dummy subscripts are mainly for the benefit of the internal syntax checker which checks to make sure that you are not passing a one dimensional array to a function which requires a two dimensional array. For example, to call the function ARavg(), which averages the values of a one dimensional array and requires the name of an array and two numbers, the function call could be written as ARavg(numarr[#],0,9). RExL's function list is divided into six `families' of functions, each of which is used for some different aspect. To make the functions easier to locate and remember, every function in a particular family (except for the miscellaneous functions family!) start with the same two letters, both of which are capitalised. The following table lists the function families: Table 2.7: Function Families Letter Abbreviation Uses of Family AR Array handling BT Binary bit operations DB Database handling DT Date operations ER Error handling KB Keyboard handling OS Operating system functions - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 16 - In the current release of RExL, there are one hundred and seventy-eight functions available. The miscellaneous functions have no special initial letters. 2.6 Expressions An expression combines constants, variables and function call return values using RExL's mathematical operators to produce a single result. For example, the expression 2+2 produces the result 4. As a general rule, the type (string or numeric) of the result of an expression is the same as that of the elements of the expression, although there is one exception to this rule. This is as follows: when strings are compared, or more properly, operated upon by the comparison operators, the return result is a numeric value. This at first may seem strange, but it makes sense when you apply the earlier suggestion that non-zero values can be thought of as being `true' and zero values being False . Thus, if two strings are compared for equality, we would expect a `true' to be returned if they were equal and a `False ' otherwise. The same convention holds true for comparison of numeric values. In RExL, a true expression is assigned the value of one and a False expression is assigned a value of zero. When using numeric expressions, all the operators previously defined are valid. When using strings however, the only valid mathematical operator is the + sign, used for string concatenation or addition. It should be obvious that attempting to subtract, multiply, divide, take powers or perform logical operations upon strings has no meaning. Examine the following expressions and satisfy yourself that they do what they say they do: Table 2.8: Some Expressions a*10 Returns the result of the multiplication of the numeric variable a and the number 10 time[0]*speed[0] Returns the result of the multiplication of the first element of the array time[] and the first element of the array speed[] a$+"end" Returns the value of a$ with the string constant "end" appended to it. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 17 - There is, however, a problem in evaluating expressions when there is more than one operator: This is to determine the order in which the sub-expressions (within the expression as a whole) are to be evaluated. For example is the expression 1+2*3 to be evaluated as 1+(2*3) or (1+2)*3? To overcome this problem, every operator has a precedence, so that sub- expressions having operators of higher precedence are evaluated before those of low precedence. When two operators have the same precedence, the expression will be evaluated from left to right, as you would expect. The complete list of operator precedence is given at the end of this section. There is one final operator, the assignment operator which is denoted by the symbol of colon followed by an equals sign :=. It is used for assigning a variable to some value. This will be covered in the next section and is introduced here so that it can be included in the table of operator precedence. Table 2.9: Operator Precedence Precedence Operator Meaning 8 () Bracketing of sub-expressions 7 ! ^ Logical NOT and exponentiation 6 * / Multiply and divide 5 + - Add and subtract 4 < > <> = <= >= String and numeric comparison 3 & Logical AND 2 | Logical OR 1 := Assignment From the table above it can be deduced that for the example given earlier, the expression would be evaluated as 1+(2*3) rather than the simple left-to-right parsing of (1+2)*3. The following table gives some examples of expressions without brackets and the equivalent bracketed expressions to demonstrate how the operator precedence table is used to determine the exact order of evaluation. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 18 - Table 2.10: Examples of Operator Precedence Expression Evaluated as Result 1+2*3 1+(2*3) 7 1*2+3 (1*2)+3 5 1+2*3^4 1+(2*(3^4)) 163 2*TAN(3.1416/4) 2*TAN(0.786) 2 2*(10=20) 2*(0) 0 2*10=20 (2*10)=20 1 "a"="b" 0 "a"<"b" 1 Don't proceed until you understand all of the results above, since the basic ideas presented there are present throughout RExL. Note particularly, the final two expressions which are not intuitively obvious since they depend on the comparison operators, and thus return numeric results. The second of the two examples involving string constants requires knowledge of the ASCII character set. For more information on this, consult the ASCII table given in appendix F. 2.7 Assignments An assignment is a special case of an expression. It assigns the value of some expression to a variable, which can be either be simple or array type, using the assignment operator :=. The return type of an expression must be the same type as the variable whose value is being assigned. Thus it is not possible to assign a string to a numeric variable or vice versa. The general format of an assignment is as follows: := The above is sometimes referred to as an LValue, short for Left hand Value. When using non-array variables, the LValue is simply the name of the variable. However, when using array type variables, you must tell RExL what element you are trying to assign a value to. Thus, you must include the relevant array element subscripts in brackets after the array variable's name. The following table gives some examples of variable assignment statements: - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 19 - Table 2.11: Examples of Assignments Expression Result of operation a:=5 a is assigned the value of 5 t$:="test" t$ is assigned the string "test" a:=a+1 a is assigned the value of a plus 1, ie: 6 t$:=t$+" string" " string" is appended to the old value of t$ to give a new t$ value of "test string" ar[0]:=10 The first element of the numeric array ar[] is assigned a value of 10 ar[a]:=a+4 The seventh element of ar[] is assigned 10 str$[1]:=t$ The second element of str$[] is assigned the string "test string" Note particularly, the third and fourth statements which seem rather counter-intuitive. Recall from the table of operator precedence that the assignment operator has the lowest precedence, and thus will be evaluated after everything else. Thus, the meaning of the statement becomes `add one to the variable a and assign the result of this addition to the variable a.' An assignment will always returns a `true' value of one. 2.8 Statements `Statement' is a generic term for a complete expression or assignment in RExL. In other words, it forms a complete RExL `sentence' which can be interpreted and executed. When an application is created, it consists of a list of executable statements, each of which returns some value (since they are expressions). RExL uses this return value from a statement to determine its next action: Whether to execute the next statement in the current list or to jump to some other location in the application. This will be more fully explained in the section on rules. 2.9 Inference Inference is the process of drawing a conclusion from a set of propositions, each of which can be either true or False . RExL operates using an inference engine: This is used to execute the application and to draw conclusions from its - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 20 - individual lines, each of which will evaluate as either true or False and are therefore equivalent to propositions. 2.10 Rules and Execution A rule is the fundamental building block of all RExL applications and is roughly equivalent to a procedure in conventional programming languages. Rules are made up of blocks of lines which may be executable statements, or further rules. Every non-blank line in a RExL application has a leading connector. This is a logical `preposition' which tells the inference engine how to link up this line with the previous and following lines in its rule. In the current release, there are three connectors: AND, If and OR. The use is an application of these connectors is best illustrated by a simple example. If The temperature is ok And It is not raining And Tell user to go for a walk Or Tell user to stay inside and play a game of chess The meaning of this should be fairly clear: The computer will tell the user to go for a walk if the temperature is ok and it is not raining, or else, the computer will tell the user to play chess. What actually happens during execution is this: the inference engine starts on the first line and asks the user `Is the temperature ok ?' (for the moment, don't worry about how the computer asks this question or how it gets the reply). If the answer to this question is yes, that is True, then the inference engine will let execution pass to the next line and ask the question `Is it raining?' If the answer is again true, then the computer will `draw the conclusion' (or more properly, execute the line) that the user should go for a walk. If on the other hand, the user had replied no, or False, to either of the questions then the inference engine would have determined that the conditions for a walk were not present, passed execution to the or clause and therefore suggested that the user play chess instead. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 21 - Whether the user is advised to stay inside or to go out, the result of the rule as a whole is the same: It succeeds, since it has successfully drawn a conclusion. RExL inserts the connectors itself. The rules for connectors can be generalised as follows: The first line in an unbroken sequence of lines will have the connector OR, unless it is the first non-blank line in a rule, which will always have the connector If (the meaning of If and OR is functionally identical). All other lines in the rule will have the connector AND. It is for this reason that the blocks of lines are sometimes referred to as And-Blocks. The rules which the inference engine follows for execution are as follows: In any rule, execution will begin at the first non-blank line of the first AND-block within the rule, that is the line with the If as its connector. It continues sequentially through the block until one of two conditions occur: Either a line returns the value zero (for False), in which case execution will jump and continue at the start of the next AND block in the rule. Or else execution successfully reaches the end of an AND block, in which case the rule returns the value True without any further statement execution within that rule. If, on the other hand, a line returns False, and execution tries to continue at the beginning of the next AND block when there is none present, then the rule will return False. 2.11 Subrules If we decided to make the application objective in assessing the temperature, rather than relying on the user to do so, we could as the user whether the temperature is within a certain range to find out whether it is really `ok' or not. We would therefore expand the definition of the The temperature is ok rule. Instead of being a simple unexpanded line, this rule would then `contain' subrules such as the following: If The temperature is more than 10 degrees And The temperature is less than 40 degrees Therefore, when the application is started, instead of RExL simply asking the question `Is the temperature ok?', it would instead ask the two more specific questions to - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 22 - determine if the temperature is between ten and forty degrees (Celsius!). During execution what actually happens is that RExL checks to see if the rule being executed can be expanded. If so, then execution passes to the expanded portion, but remembers where the rule was `called' from. It then executes the lines within the expanded rule and eventually returns a True or False value to the original caller of the rule. So, going back to the example, when execution reaches the rule `Is the temperature ok?', it expands the definition and asks `Is the temperature more than 10 degrees ?' If the answer is `yes' or True, then the next question is asked, `Is the temperature less than 40 degrees?' If the answer is again True, then both conditions in the expanded rule are True and so the the rule would succeed, return True and RExL will then ask whether it is raining or not, continuing from where it left off in the parent rule. If, on the other hand, the user replies `no' or False, to either of the questions about temperature, then the expanded rule fails and returns False to the parent rule, thus making the conditions for a walk unavailable, and therefore suggesting that the user play chess. Every application has a master rule (sometimes known as a `main rule') which is called by RExL when the application starts. In the current release of RExL, this rule is called Main Program and cannot be changed. All other rules can therefore be considered as subrules of the main rule. It is very important that you understand thoroughly the action of the inference engine in RExL, and how it executes rules and returns values. All RExL applications are based upon the ideas presented in this and the previous section. You should reread them if you are not happy with them. 2.12 Rule Modifiers The rules in the previous two sections were basic rules. That is, that they acted as rule calls and were executed every time the application called them. There are, however, a number of different variations upon this theme. These rule modifiers perform some action other than a simple rule call. The six rule modifiers are as follows: - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 23 - Table 2.12: Rule Modifiers Abbreviation Used for BackTo Rule recall Not Return inversion of rule call While Continuously execute rule while true Multi Make rule multi-pass Single Make rule single-pass Zap Reset status of single-pass rule In the editor, the modifiers are placed between the line's connector and the name of the rule. The function of the six modifiers are explained in the next six subsections. 2.12.1 BackTo Whenever a rule is called by an application, RExL stores the place in the listing where the rule was called from in a special area known as the call stack (so called because rule calls are `stacked' there). The BackTo modifier is used to clear the call stack back to the last instance of some previous rule. This can be used when for example, when the user selects a menu option to restart an application, the application could contain a line such as: And BackTo Main Program BackTo may also come in useful when an error occurs and the program needs to restart the execution from some point. Note that if the rule specified doesn't exist in the call stack, then the application will end, since it can't locate any place to restart from. 2.12.2 Not When Not is applied to a rule, it reverses the logical return value of the rule. Thus, if rule call returns True, but the rule is modified by the Not, then the rule will evaluate as False. The Not modifier is mostly used for logical tests which are easier to evaluate as True than False (and vice versa). 2.12.3 While The function of the While modifier is to execute a rule continuously while its return value is True. This could be useful for doing some work in a database, where the rule is designed to fail when the end of the database is reached. A - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 24 - rule call which is prefixed by While will always fail because of the nature of the modifier. 2.12.4 Multi By default, all RExL rules are multi-pass rules. This means that a rule is expanded and evaluated each and every time it is called (although this is not standard for expert systems, where all rules are single-pass). However, it is sometimes useful to have rules which are not reevaluated every time they are called, but save their status from one call to the next. These rules are known as single-pass rules. The Multi modifier is used to make a single-pass rule a multi-pass rule. 2.12.5 Single The Single modifier performs the reverse of what the Multi modifier does: It makes a multi-pass rule (the RExL default) into a single-pass rule. 2.12.6 Zap When a one-pass rule is set up and has been evaluated, but for some reason, needs to be to be reevaluated (because, for example, of some changed condition) then the Zap modifier can be used to reset the status of the one-pass rule to unknown, and thus the rule will be reexecuted when it is next called. 2.13 Other Modifiers Every line, other than a simple rule call, must have a modifier attached to it. We have already some across the list of the six modifiers for rules in the previous section. That list is now completed with the list of modifiers for the other line types: - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 25 - Table 2.13: Other Modifiers Modifier Applicable to [Expr ] Statements [Dialg] Input and output [Dsply] Screens [Help ] Screens [Menu ] Screens [Print] Screens Note that all non-rule modifiers are surrounded in square brackets. This is to help the programmer distinguish at a glance whether the line is a rule or screen/statement. The final five modifiers in the table are applicable only to screens and are dealt with in the chapter on the screen designer. The [Expr] modifier at the beginning of a line indicates that the line is a statement (either an assignment or expression). Expressions, as noted before, can return either a zero value for False or a non-zero value for True, while assignments will always return True. Examine the following list of statements and satisfy yourself that they return the values indicated. Table 2.14: Expression Truth Values Statement Returns 1 True 0 False 123*23 True 10-10 False a:=10 True a=10*("h"="h") True - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 26 - - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 27 - Chapter 3 Quick Start 3.1 Introduction In this chapter, we'll go through the process of creating a small application in RExL. First, we'll use the editor to create it, and then the runtime module to run it. In the final section, we'll use the integrated debugger to debug the application. If you haven't read the chapter on RExL's language, you should do so now, since the application developed there will be created here, and the editor won't make much sense unless you understand the language. Every RExL application is stored on disk in two parts, the first part is the application image. This is the listing which you can edit using the editor. The second part is the screen file which stores the screens used in the application. The application image file has a file extension of ".RXL" while the screen file has one of ".SCR". Changes to the screen file are included immediately, while those to the application listing are saved only when RExL is instructed to do so. It is for this reason that you should not modify any screens in an application without updating the application image on disk, since the two files may go out of synchronisation. The RExL system also comes in two parts. The first part, the editor, is used for creating and maintaining the application and for designing the application's screens. The second part is the runtime-debugger which is used to execute and debug the application. This two part approach is used because it maximises the amount of memory available to each module. The two modules are linked, so that you can run and debug you application without having to exit from the editor and explicitly run the debugger. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 28 - 3.2 Creating an Application Start the editor by typing rexl at the DOS prompt and press . After a second or two, the editor screen appears. If any error messages appear, just press a key and ignore them. The menu bar across the top of the screen uses the standard menu keys of and to move the hilite bar and to select an option. The hilited letters in the menu titles (ie `F' in File) can be used to select an option as can a combination of the Alt key and the letter (ie to select the options menu). We want to edit the application, so select the Edit option from the main menu and press . The first line in the central edit window will be hilited in gray, the connector `If' will appear at the left end of the hilite bar and the cursor will be placed a few characters in from this. The first line of our application was `The temperature is ok', so just type this in to the editor and press . The cursor and hilite bar will then jump to the next line and an `And' connector will appear at the start, in the same position as the `If' of the previous line. The rules for the automatic insertion of connectors will be explained shortly. Enter in the next line of text, `It is not raining' and again press to go to the next line (You can press to proceed if you want to, just be careful not to insert blank lines, since these will change the meaning of the rule as we will soon see). The final line of this And-Block is `Tell the user to go for a walk', so enter this. The first And-Block of our mini-application has now been finished. We now need to enter the final line, telling the user what to do. Place the hilite bar over the `Tell the user to go for a walk' rule and press the key. This will expand the rule. Note that the rule name is now displayed on the line underneath the main menu bar. To display the RExL's advice, we'll use the `DISPLAY()' function which we met earlier. We'll need to tell RExL that what we are entering is a statement, so press the key. This will generate the `[Expr]' line modifier and place it immediately after the `If' line connector. If the modifier were omitted, RExL would assume that the line was a rule and - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 29 - not an expression. With the modifier in place, enter the expression `DISPLAY("You should go out and have a walk")' This completes the first section of our application. Press to return from the sub rule to the parent rule (note that the rule name display area now displays the name `Main Program'). Press (or ) twice, so that a blank line now exists between the first AND-block and the hilite bar. You'll notice that the connector at the beginning of the line has now become `Or'. The rule which RExL follows for generating connectors is simple. Every line begins with `And', unless one of two conditions is true: The first line of an AND-block will have the connector `Or', unless the line is the first line in the rule, in which case the connector will be `If'. All other non-blank lines will have the connector `And', while blank lines have no connector. Type in the text for the `Or' condition: `Tell the user to stay inside and play a game of chess'. Press to expand the rule and then enter the expression `DISPLAY("Stay inside and play a game of chess")', not forgetting to press to specify the `[Expr]' modifier. 3.3 Running the Application The application is now ready to run. Press to save it and select the `Run' option from the main menu (by pressing , or to return to the main menu and using the cursor keys to select). Select the first option in that menu, `Run', and press . Within a few seconds, the application should begin running. The screen will change to a light gray background with two cyan boxes in the center of the screen. The upper of the two boxes will contain the name of the first rule in the application, `The temperature is ok'. Underneath this, there is a small menu with two options, true and false. When one of these options is selected, its value returned to RExL directly. Recall from the explanation of the application in the previous chapter, that the user would be advised to go for a walk if `the temperature was ok' and `it is not raining'. Therefore, for this conclusion to be drawn, the first reply must be true (select the `True' option from the menu) as well as the second option (`True' again). When both conditions have been satisfied, RExL will display the - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 30 - string `You should go for a walk' on the monitor. Selecting a value of false for either of the conditions will cause RExL to draw the other conclusion, that the user should play a game of chess. When RExL has printed its advice, the application will terminate and you will be returned to the editor. If this happens too quickly to see the result, press from within the edit window in the editor to display the user screen, the screen as it existed before the editor was loaded. You should run this application a few times and satisfy yourself that you understand what it is doing. 3.4 Expanding the Application We will now expand the application using custom screens designed using the screen designer. Recall from the language chapter that we wished to make a more objective assessment of whether the temperature was ok by adding two sub rules to that rule. Instead of doing this, we shall instead add an input screen to get the actual temperature from the user and to perform numeric comparisons upon it directly. Expand the definition of the `The temperature is ok' rule and type in the following `Input a value for temperature' and press . A small menu will appear with six options on it (these are the different screen types available). We want the program to perform some input and output, or dialog, with the user, so select the `Dialog' option and press . The editor screen disappears and you will see the start up screen of screen designer which is filled with the quarter tone character `�'. Move somewhere slightly to the left of the center of the screen and type `Enter the temperature :' We now want to define an input field, so that the user can input a value to RExL. Press to start the field definition, press once to make the field ten characters wide, and press to accept that size. A box will appear asking for an `input expression'. As with assignments, this must be an proper LValue. Type in `Temperature'. This will the name of the variable which we'll use to store the value of the temperature in (note that the variable doesn't end in a dollar sign and is - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 31 - therefore a numeric variable, suitable for storing temperature values). Press to accept this input expression. The field will now be replaced by a series of ten question marks which are used to indicate an input field. Press to save the screen and to exit from the screen designer and return to the editor. Note that the line's modifier has now become `[Dialg]' to indicate a dialog screen. Move to the next line and enter the expression `Temperature>10' and on the following line, the expression `Temperature<40', remembering to press each time. Press to return to the main rule, enter the `Tell user to go for a walk' rule, place the hilite bar over the `DISPLAY()' statement and press (or ) to delete the line. Type the string `Go for walk screen', press and select the `Display' option from the screen menu. The `Display' screen type is used to display a screen and then wait for a key to be pressed, it's useful for displaying some information and then pausing until the user has read it. When in the screen designer, press to begin marking a block. Move to the bottom right hand corner of the screen using the arrow keys ( and can also be used to do it in two keystrokes) and press to select the block. The block menu will now appear: Select the `Paint' option to color the marked block. Use and to change the foreground (text) color and and to change the background (paper) color. Change it to something that looks nice on your monitor. When you have finished painting the block, press to accept. Press to remark the block, select the `Box' option from the menu and select one of the box types from the new menu which appears. Make sure that the first option on this menu is `overlay' and not overwrite, otherwise the text you typed in earlier will be deleted. You might like to try this a few times to see the different types of box available. Move to the center of the screen, type the string `You should go for a walk' and save the screen using as before. Using the same procedure again, delete the other occurrence of `DISPLAY()' and replace it with a display screen. When you have done this, run the application again. This time, instead of RExL asking you `Is the temperature ok?', it will ask for a temperature value. Enter some value. If the value was between 10 and 40 then both of the comparison - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 32 - expressions entered after the screen in the temperature rule will be evaluated as true and hence the rule will succeed. RExL will then enquire, using the true/false menu, about the next condition for a walk, whether it is raining or not. As before, if true is selected, RExL will display the `Go for a walk' screen, otherwise it will display the other result. Run this application a few times to make sure that you understand how it works. 3.5 Debugging the Application When you are developing an application in RExL, it is very useful to be able to follow the thread of execution to make sure that the application is doing what is you expect it to. The debugger, which is incorporated into the portion of RExL which runs the applications (known as the runtime module), can be used to do just that. Run your application again, but this time, instead of selecting the `Run' option from the run menu, select the `Debug System' option. After a few seconds, the debugger will appear. The interface is much the same as that of the editor and where the comparison is meaningful, the keystrokes are the same, so you shouldn't have any difficulty using it. The screen layout is slightly different from the editor. The main differences are as follows: o To the immediate left of the connector of every non- blank line, there is a status character. This can assume one of three values, `?', `�' and `X', depending upon what the logical status of the line is. `?' for unknown or unevaluated, `�' for logical true and `X' for logical false. o The line about to be executed by RExL is indicated by an arrow between the line modifier and the line's text. Press . This will trace the application. Depending on the current line type, tracing has different results: If it is over a rule, then the debugger will enter the rule, as if you had pressed , and it will place the debugger on the first non-blank line of that rule. If the line is a screen, - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 33 - then the screen will be activated and control will be returned to the debugger when the screen terminates. If the line is an expression, then the line will be evaluated and control again returned to the debugger afterwards. There are a few more conditions which trace controls, these will be covered in the chapter on the debugger. When you pressed , the hilite bar entered the rule and was placed over the first line in it (which is the screen). Press again to execute the screen. Enter some value for the temperature in the prompt box which appears (try 30). When you press , the screen terminates and the debugger regains control of execution. We will now place a watch on the variable `temperature'. A watch is an expression which is evaluated (or watched) every time that RExL executes a line of code. The watch can be entered in one of two ways: The easiest is to place the cursor somewhere in the word `temperature' on the debugger's screen and then press ( also works). When there is one present, the debugger will pull a word from underneath the cursor and place it into whatever box you call up, in this case the watch expression box. If the word appears, just press to accept it, otherwise, type in the word `temperature' and press . The expression will be placed in the `watch window', the box on the lower portion of the screen. Following the expression you entered, there will be a colon followed by the current value of that expression, in this case, the value you typed in in the screen. You can set a watch on any valid string or numeric expression. Press again to execute the line. If you entered a value of 30 for the temperature above, then this line will be true, and the line status indicator at the left edge of the line will display a `�', if you entered some other value causing the line to fail, then the status will be false as indicated by a `X'. Assuming you entered 30, the debugger places the hilite bar on the final non-blank line in the rule which you can now trace. The hilite bar should now be beyond the last line, to indicate that the rule has been evaluated and that execution is about to return to where the rule was called from. Trace again and see this happen. The status indicator of the first rule in the main program should now be `�' to indicate that it was evaluated as true. We will step the next two lines. Stepping is much the same as tracing, the only difference being that if the line being stepped is a rule, then the debugger will not enter the rule - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 34 - definition, it as it does in trace. Press to step the application. You'll now be presented with the familiar true/false menu screen. Select false and note that the debugger has filled in an `X' as the logical status of the failed rule and left the status of the last rule in the first AND-block as unspecified, using `?'. The hilite bar will now be placed upon the first line of the alternative, the second `AND'-block, so press to step it. The debugger will not immediately regain control of the application since the screen type being displayed is a `display' screen and so requires a key press to end it. The hilite bar will now be on the final (empty) line of the application. Press one of the execute keys (, or space) to terminate the application and return to the editor. Debug the application a few more times to make sure that you understand how stepping, tracing and watching work. If you want to delete a watch expression, press to switch to the watch window and then or to delete the watch. Press again to return to the code window. There are three other useful features in the debugger which were not covered above. These are the `Execute To' key, , the `Evaluate Expression' key, , or and the `Breakpoint' key, . When you press on a non-blank line, the application will run until it reaches that line. This is useful when you are somewhere within an application in the code window and you wish to set a temporary breakpoint. For a full discussion of the features in the debugger, consult the chapter on the debugger. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 35 - Chapter 4 The Editor This chapter covers the functions and capabilities of the editor in depth. Because of its size, the screen designer is documented in a chapter of its own, rather than in this chapter. You should have read the chapter on RExL's language before you use the editor, since the two are linked very closely. 4.1 Introduction RExL's editor uses the concept of `folding text' to make the programmer's job easier. As was explained in the previous chapter on the structure of RExL programs, applications are built up in a pyramidal manner, using rules which call further rules and so on. This gives the application a two dimensional structure which has been generally ignored by traditional `flat file' editors. RExL, on the other hand, understands this hierarchical structure and allows the programmer to access procedures immediately, without having to do searches or large cursor movements. You must understand this folding-text approach before you progress to the more complex aspects of the editor. The editor `understands' RExL's language: Whenever a line of RExL code is entered, RExL will check the line's syntax to determine if the line is syntactically valid. If it is, then the text will be scanned for variables which are then be placed into the variable list. The syntax analyser checks not only for errors such as incorrect parameter lists and invalid mathematical operations, but also for less obvious mistakes such as arrays with incorrect number of dimensions. When a new rule is defined, it is placed into the rule list, which can then be used to locate it rapidly. A similar procedure applies to screens which also have their own list. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 36 - RExL's editor user interface is based loosely on Borland's integrated editor, as present in Turbo Pascal versions 4.0 to 5.5 and Turbo C, versions 1.0 to 2.01. Anyone who has used these editors should have no difficulty using RExL. 4.2 Interface Conventions There are a number of keystrokes and conventions which RExL adheres to throughout the system. These are documented here. o Cursor: The cursor can assume one of two shapes, depending on whether it is in insert or overwrite modes. When in insert mode, the cursor will be the same size as the character block and text entered will be inserted into the current cursor location, pushing the text to the right of the cursor off to the right, possibly losing some at the end of the input area. When in overwrite mode, the cursor will be two pixels high and placed at the bottom of the character box. Text entered will erase any text which was previously present at the cursor position. The key is used to toggle between insert and overwrite modes. o Cursor Movement: The and arrow keys move one character left and right respectively. and move one word left and right. and move to the beginning and end of the input area, unless in the screen designer, where they move to the left hand edge and the right hand edge of the screen. and move up and down by the size of the current window, unless in the screen designer, where they are used to move to the top and bottom of the screen. will delete the character to the left of the cursor, moving the text to the right (and the cursor) one character to the left. will delete the character underneath the cursor, moving the text to the right one character to the left. o Input: When RExL requests string input, there is generally a default value which is hilited in yellow text on magenta background within the dialog box. RExL interprets the first keystroke pressed in the dialog box as follows: Pressing one of the cursor movement keys will deselect this default so that it - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 37 - may be edited. A non-extended keystroke (these are the letters A to Z, the digits 0 to 9, punctuation marks and all characters whose ASCII codes are greater than 128) will cause the selected string to disappear and the keystroke entered to appear as the first character of the string. Any other keystroke (, , , , the function keys, and keystroke combinations and so forth) will terminate the dialog and return you to the place from where it originated. Once the dialog has been deselected, input can continue using the standard editing keys. In the current release of RExL, the string entered cannot be wider than its input area. o Scrap Buffer: The scrap buffer is a small one line buffer which can be used to copy and paste small chunks of text from one input area to another. The contents of the scrap buffer are displayed between the curly brackets {} on the status line at the bottom of the editor screen. If the buffer area would overflow on account of the length of the string placed in it, RExL will display the first six characters of the string followed by an ellipsis (three dots) followed by the last six characters of the text. Text is entered into the scrap using and pasted from the scrap using . The scrap may be used, even when it not displayed, such as when in the screen designer. Note that when you terminate RExL lists by pressing , the previously hilited item will be pasted into the scrap. Terminating by pressing any other key will not perform the paste. Note that inserting text from the scrap will overwrite any text to the right of the cursor. o Undo: In all string input areas, you can press to undo any changes to the original string. o Help: On line help is available at all times in RExL. There are two forms of help. The first is context- sensitive, meaning that the help which appears is relevant to whatever you are currently trying to do. This help is activated by pressing the key. Language help will bring up a help screen related to the language keyword which the cursor is placed over. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 38 - This is activated by pressing . At any time, the last help screen to be displayed can be re-displayed by pressing . o Window Move: Most windows in RExL are movable using the standard arrow keys when is active. This key is normally located at the top right of your keyboard. Note that no windows may be moved over the status line at the bottom of the screen nor the menu bar at the top of the screen. o Macro Recording: You can record macros `on-the-fly' from anywhere within RExL. A macro is a series of keystrokes which can be `recorded' and `played back'. To switch on the macro recording facility, press . A dialog box will pop up requesting the name of the macro which you are about to start recording. If you don't want to assign it a name, just press . RExL will then ask for a keystroke to attach the macro to (press to abort the record). While you are recording, an `R' will appear in the top left hand corner of the display, press again to turn the macro record off. You can save the macros to disk using the Options/Save macros menu option. Macros can record and replay up 512 keystrokes. The list of macros defined can be displayed by pressing . To play back a macro, hilite the name with the hilite bar and press . While a macro is playing, a `P' will appear in the top left corner of the display. o Helix Searching: When using menus in RExL, there are two methods which can be used to select options quicker than using the cursor keys. - Initial letter: Most fixed size menus in RExL have initial letter searching. In this mode, all you need do is type the initial letter of the menu option and it will be automatically selected. The initial letter is usually hilited in light blue. - Helix searching When the number of items in a list or menu is variable, for example as in the rule list, the hilite bar can be brought to an option incrementally by typing the name - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 39 - of the item you are searching for. The portion of the item entered is hilited in a slightly differrent color from the normal hilite bar. The hilite bar will move to the next item which matches the letters entered already, with those letters being colored black on a light gray background. Press to delete letters from the helix search list. For example, if you had a menu with three items in it, One, Two and Three, when the letter T is pressed, the hilite bar moves to the second option, and the first character in the menu bar becomes black on gray. When h is then pressed, the menu bar moves to the next option and hilites the letters Th. o File Name Input: Whenever RExL requests a file name, such as when selecting a file to load into the editor, you may either enter a proper file name, otherwise you can enter a file specification including any of the wild-card characters, ? or *. When using the wild-cards, RExL will give you a menu listing those files which match the file specification entered. Any directories in the current search directory are also displayed in the list and you can change to any one by selecting it from the list. The list of files matching the file specification will be regenerated from the new current directory. For all directories other than the root (when performing wild card file selections) the first option on the menu will be "..\". Selecting this directory will being you to the directory directly above the current one. You can terminate the menu file name select by pressing to select a file name, or to abort the selection. 4.3 Editor Basics The editor is started by typing `rexl' at the DOS prompt. You can optionally supply a filename for RExL to load immediately into the editor. Ther is one command line option which may be passed to the editor, the `-l' option. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 40 - This is used to tell the editor that it is running on an LCD display. Once the `-l' option has been specified, it will be saved to the configuration file, so it need not be specified again. The editor does two things before it becomes ready for input. Firstly, it attempts to load the RExL configuration file, REXL.CFG. If there is no configuration file present, RExL proceeds without comment. Secondly, if the configuration is so set up, the editor will load the index for the help file, if it is unable to do so, an error will be displayed. The configuration file stores information about the position and colors of the windows in \rexl, the beeping, help, function case, window explosion, bracket matching, list size, LCD and DOS screen storage status flags. When searching for the help file, RExL will first search the current directory and then the directory specified by the REXL environment variable. The editor uses only one command line parameter, -l. This is used to tell RExL that an LCD monochrome screen is attached to the computer which it is running on and to set the screen colors accordingly. Note that the editor can autodetect a standard monochrome screen, but not an LCD monochrome since the hardware does not permit it. Once the -l option has been specified once, RExL will store it in its configuration file along with the rest of the colors and various other configuration data. Once the above procedure has been completed, you will be presented with the main editor screen (note that you can't have all the menus pulled down at once, as they are in this figure! The dots indicate where the menu is normally displayed): [Figure omitted in disk manual] The bar at the top of the screen has five pull down menus. These can be activated by pressing the left and right arrow keys to move from one to the next, and pressing the enter key to select the hilited menu. Once selected, the menu will drop down and a standard selection menu appears. To the right of the six menu titles, is the name of the RExL file which is currently being edited. If the editor has been started with no application name given on the command line, then this file name will be NONAME.RXL. Note that if a file of this name exists in the current directory exists already, then it will be loaded. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 41 - The bottom line of the screen is the status line, and it is here that RExL posts the status of the editor as well as any error messages which are generated. On the left hand end of the status line, between the braces {} is the scrap buffer display, as explained earlier in this chapter. The `Memory :' display on the status line shows the amount of available memory in the editor. If this becomes lower than about 20000 bytes, you may run into lack-of-memory problems. The `Level :' field displays the current rule `depth' which the editor has reached. We will cover rule depth in detail further ahead in this chapter. This has a maximum of 100 levels which is more than enough for most applications. The six menus on the main horizontal menu bar have contents as follows: 4.3.1 File menu 旼컴컴컴컴컴컴컴� � Load � � New file � � Save � � Write to � � Remove � � Change dir � � Default drive � � OS shell � � Quit � 읕컴컴컴컴컴컴컴� The file menu has the following nine options: 1. Load: This option controls the loading of applications into RExL. When this is selected, a file name dialog box (as explained above) appears. This will have as an initial value, the string "*.RXL". 2. New file: This option is used to clear the contents of the editor, as if the editor had been restarted from the DOS prompt. `NONAME.RXL' will be loaded if is present in the current directory. 3. Save: When this option is selected, the application currently in memory will be saved under the name displayed on the top line of the screen. As a short - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 42 - cut keystroke, you can press from within the main editor window. 4. Write to: This option allows the name of the current application to be changed. When it is chosen, a dialog box will appear requesting a name for the current application to be written to. If a valid name is entered, the application in memory will be saved to disk under the new name and the screen file will be copied. If there is not enough disk space on the current disk drive for the new files, then the operation will fail. The next menu option may be used to remove unwanted files from disk. 5. Remove: This choice allows you to delete a file from disk. You may need to do this is you want to save a file on disk, but are unable to do so through a lack of disk space. 6. Change Dir: This option will allow you to change the active directory. The format used here is much the same as that used in the file name input routine, the only differences being that no file names are displayed in the list and that the current active path (drive name with full directory) will be displayed on the status line at the bottom of the screen. 7. Default Drive: When this option is chosen, a menu will pop up displaying the list of available DOS disk drives. As with the directory selection above, the current active path is displayed on the status display line at the bottom of the screen. 8. OS Shell: If you want to run a DOS command, but do not wish to exit from the editor permanently, choose this option to go into a DOS shell. While you are in the shell, you should not, under any circumstances, run any T&SR programs (such as Sidekick, ScrGrab and so forth), since these programs change critical area of the computer's memory which may cause it to crash unpredictably when you return to RExL. When you are finished in the shell, type `exit' at the DOS prompt to return to RExL. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 43 - 9. Quit: This option terminates RExL and returns you to DOS. If the application currently in memory has been altered, then RExL will prompt you to see if it should be saved. Selecting either of the options will perform the action and then return you to DOS, pressing any other key will return you to the menu. 4.3.2 Edit menu 旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴커 � Edit � � Default screen: � 읕컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴켸 The edit menu contains two options. Selecting the first option, `Edit' will bring you directly into the edit window to begin creation or editing of your application. The edit window will be covered in detail further ahead in this chapter. The second option, `Default screen:' is used for setting the name of the screen which is to be preloaded into the screen designer. When this option is selected, the screen list will be generated and a screen may be chosen to be made the default. If a valid choice is made, then the screen designer will be started so that the default screen itself may be edited. Default screens are most useful when all screens in an application must have the same set of colors, have a few fixed fields or whatever. To clear name of the default screen from the listing, the first option in the screen list, `Clear default screen', should be selected. 4.3.3 Run menu 旼컴컴컴컴컴컴컴컴컴� � Run � � Debug application � 읕컴컴컴컴컴컴컴컴컴� The run menu has the following two options: 1. Run: When this option is selected, you will be requested to save the application which is currently in memory (if necessary) and the runtime module will be called to run it. Unlike the function of the next option in this menu, the debugger will not be enabled - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 44 - when the application starts. Note that you can enter the full screen debugger at any time during the running of an application by pressing the keystroke (stands for Debug). When attempting to locate the runtime module, the editor first searches the current directory, then the directory specified by the RExL environment variable, and finally, the entire DOS path, if one exists. If the editor is unable to locate the runtime module, an error to this effect will be generated and the editor will continue running. 2. Debug application: As with the previous menu option, the application in memory will be saved and the runtime module called if possible. The only difference from the previous menu is that the debugger will be started in full screen debug mode, as if had been pressed upon initiation of the application within the runtime. 4.3.4 Lists menu 旼컴컴컴컴컴컴컴컴컴커 � Rule list � � Screen list � � Unused rule list � � Unused screen list � � Variable list � � Function list � 읕컴컴컴컴컴컴컴컴컴켸 This menu gives you access to all the lists of entities which are defined the current application. Most of the lists have special `hot-links' to other, more specific, lists. These are mentioned briefly at the end of this subsection and covered in more detail further on. All of these lists are also available via hot-keys from within the main editor window. Consult the section on editor keys for more information on this. The lists run menu has the following six options: 1. Rule list: This list contains the names of all of the rules which are currently defined in your application. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 45 - 2. Screen list: This list contains the names of all screens defined in the currently active screen file. 3. Unused rule list: This list shows all rules which, although defined in the normal way, are not actually referenced by the application. Pressing within this list will delete the unused rule from the application.1 4. Unused screen list: This list gives all screens which are not referenced in the current application. As with the unused rule list above, press to delete the unused screen from the list and free up the space it occupies within the screen file. 5. Variable list: This list contains all variables. The status line at the bottom of the screen displays the type of the variable, whether numeric or string, and whether it's an array or a simple variable. 6. Function list: This list contains all the functions available in RExL. Press for help on the hilited function. 7. Graphic rule display: This displays the rule call tree for the current rule. This is covered in more detail in its own section. All the list windows are movable by pressing , using the arrow keys to position and pressing , or to terminate the window move. Note that all lists in RExL feature helix searching. You can also output the contents of any list to a file (or the printer) by pressing , as in DOS. If you terminate any of the lists by pressing , then the choice which you selected from that menu will be placed into the scrap buffer, ready for pasting using the keystroke. ____________________________________________________________ 1. Note that deeply recursive rules (those which do not have a reference to themselves in the immediate rule definition) which are not used by other rules are not currently detected as being unused. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 46 - 4.3.5 Options menu 旼컴컴컴컴컴컴컴컴컴컴컴� � Load macros � � Save macros � � Beep off � � Function lower case � � Exploding windows off � � Dictionary size: 500 � � Help fast � � Bracket match on � 읕컴컴컴컴컴컴컴컴컴컴컴� The options menu controls various system parameters and features not directly connected to the editor per se. 1. Load macros: Any macro definitions you define in the editor may be saved to disk for later retrieval using this menu option. The macro file format is constant across the RExL product range, so that macros defined in the editor may be used in the debugger or in the database manager and so on. Macros are explained in more detail at the beginning of this chapter. 2. Save macros: This option allows you to save macros which can then be reloaded at some future time using the load option above. 3. Beep off: By default, RExL beeps whenever it encounters an error. This beeping can be toggled on and off by selecting this option. 4. Function lower case: By default, all functions in RExL are displayed in their natural case. This is that functions which are members of families are displayed with the first two or three letters capitalised, while the miscellaneous functions are entirely capitalised. This option is used to toggle between upper (or partially upper) case function name display and lower case. 5. Exploding windows off: In its default state, all windows in RExL open instantaneously upon activation. This option can be used to make windows `grow' to full size on the screen. This is only a visual effect and has no effect upon the application. Selecting the option a second time will turn the option off again. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 47 - 6. Dictionary size: The dictionary size is the size of all lists in RExL. This defaults to a list size of 500 items, but can be changed by using this option. Each list entry consumes four bytes of memory. If you are dealing with a particularly large application, you may want to make this list size smaller to conserve memory. 7. Help fast: As explained earlier in this chapter, the editor loads in the help file index when it starts. This is done so that the help can respond instantly to requests. However, the help file index requires about 9000 bytes of memory, so again, if developing large applications, you may wish to disable the automatic loading. The help will then load the index for every request which will slow it down somewhat. 8. Bracket match on: When entering expressions, RExL will automatically hilite matching brackets. This is to help you locate incorrect bracketing in complex expressions. You can toggle this feature by selecting this option. 4.3.6 Import menu 旼컴컴컴컴컴컴컴컴� � Save to ASCII � � Load from ASCII � � ASCII Options � 읕컴컴컴컴컴컴컴컴� RExL will import and export properly formatted RExL source files in ASCII format. This is mainly done for purposes of documentation and hard copy archival. All attributes of an application are saved, including screen colors, text and screen fields. The ASCII file can become large because of the amount of information contained in it, typically, the size of the listing file is seven to ten times the size of the combined listing and screen files. The foreground and background colors of screens in the application are saved in the ASCII listing file as letters which map directly to colors. The colors are mapped as follows: - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 48 - Table 4.1: ASCII Color Translation Table Letter Color Letter Color 0 Black 1 Dark gray B Blue b Light blue G Green g Light green C Cyan c Light cyan R Red r Light red M Magenta m Light magenta Y Brown y Yellow W Light gray w White The listing file will save the contents of screens correctly, but certain characters, such as the ASCII end- of-file marker, character 26, may confuse other DOS programs which read and write ASCII files, notably Sidekick, WordStar and so on, although RExL will load the file correctly. Furthermore, the ASCII newline and carriage return characters, characters 10 and 13 respectively, may unsynchronize the listing file so that it will not load properly. There are two active options and one sub-menu within the Import Menu. These are as follows: o Save to ASCII: The application currently in memory will be saved to disk as an ASCII listing file. The file name will be the same as that of the parent application, but with an extension of .LST. While the listing is being saved, its progress will be posted on the screen. o Load from ASCII: A standard file name input box will pop up when you select this option. The default input string is "*.LST" which you can edit in the usual manner. When you have selected a file to load, RExL will being to process the file. Note that the format of the file is very strict and you shouldn't edit the ASCII listing, in case the editor doesn't accept it. The listing file will be saved in the current directory (irrespective of where the listing file is) under the same file name, but with an extension for the application image of .RXL and one for the screen file of .SCR. If either of these files already exist, then they will be backed up: The application image being given an extension of .BAK and the screen file one of .BKS. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 49 - o During the loading process, all executable lines (that is screen fields and lines in the application image) will be displayed in a box underneath the progress box which also displays the percentage of the lising file loaded, for your convenience. This is done so that when an error occurs, it can be displayed on screen and edited. o ASCII Options: This is a sub-menu which contains the following two options related to ASCII loading and saving. - Strip unused vars: This is a yes/no toggle option. When set to yes all variables which are listed in the ASCII listing file, but which are not used in the actual code of the application, are discarded and not placed in the newly generated variable list. When set to no, these unused variables are not removed. - Emit screen codes: This is another yes/no toggle option. When it is set to yes, the color codes for the screens in the listing are emitted along with the text of the screen. For purposes of system documentation, this information is generally not needed, and this option can therefore be set to no. 4.4 Using the Editor Once you have selected the Edit option from the main menu, RExL is ready for you to start creating your application. All lines entered are either statements, rules or screens. The rules for entering each line type are laid out in the next three sections. The editor will automatically assign the line connectors, If, AND and OR according to the rules for block connection. That is, the first non-blank line in a rule uses If, the first lines in the remainder of the and-blocks use OR, while all remaining non-blank lines use AND. Blank lines have no connector. A rule may be declared as one pass by pressing within the edit window. Since the one-pass modifier applies to the rule as a whole, the modifier [OnePass] is displayed - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 50 - in the rule name box at the top of the edit window. As with the rule type modifiers, toggles its modifier. 4.4.1 Entering Statements Statements, which include both assignments and logical expressions, are the simplest to specify, by pressing . However, before RExL will accept a statement, it must be syntactically valid. The statement syntax checker scans the line for invalid syntax, incorrectly dimensioned arrays and incorrectly used functions and variables. When it encounters an error, it signals the location of the error on the input line with an red indicator. A keystroke will clear the error and return control to the editor, where the error can be corrected. If the line is syntactically correct, the syntax checker will recover all variables from the line and add them to the variable list, available on . Any new arrays found in the statement will be dimensioned to ten elements in all their declared dimensions, although this can be changed through the variable list, explained shortly. In certain cases, when comparing strings and using the logical return values, you may need to bracket the string sub-expression to avoid incorrect parsing. For example, an expression such as a:=10+"a"=a$ will require bracketing since the sub-expression 10+"a" will be evaluated first, since addition has a higher precedence than equality. When the line has been passed as correct, the syntax checker then converts the text into symbolic tokens which are stored more efficiently in memory than text alone. This has a number of side effects: o Variables are converted to internal variable reference numbers: It is for this reason that when a variable is entered a second time, the case in which it finally appears will be the same as that in which was first entered. For example, if you enter an expression such as MyAge:=10 (where MyAge has not been defined previously) and later on enter the expression myaGE=12, then the string myaGE will be converted to the earlier occurrence of MyAge. o Numbers are stored in one of four forms, depending on their size. Whole integers between -127 and +127 - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 51 - inclusive are stored exactly as one byte numbers, whole integers between -32767 and +32767 are stored exactly as two byte integers, whole integers between -2147483647 and +2147483647 are stored exactly as four byte numbers. All other numbers are stored as as eight byte double precision real numbers, to an accuracy of approximately fifteen digits. When you enter a number, it will be converted into the appropriate internal format. Any superfluous, or unstorable decimal places will be discarded. 4.4.2 Entering Rules Rules are the simplest entities to enter in RExL: Any line without a modifier defaults to a rule. When an unknown rule is entered, it is entered into the rule list immediately. As with variables, rules are stored by reference, so that once a rule has been entered, its case cannot be changed. The text of rules themselves may be edited, and the editor will change all references to reflect the new edition of that rule. Rules can take any of the modifiers, BackTo, Not, While, Multi, Single, Zap or a blank modifier. Each modifier modifies the meaning of the rule as explained in the chapter on the language, a blank modifier simply means `call the rule' and do not modify its return value. To set the line's modifier, press followed by the initial letter of the modifier. Thus will generate a Zap modifier. Pressing the key again will remove the modifier and return the rule to its unaltered state. The full list of modifiers and keystrokes is given at the end of this chapter in the key reference. To expand the definition of a rule to include subrules, statements, screens and so forth, press . The name of the expanded rule will be placed in the rule name box at the top of the edit window and the hilite bar placed on the first line of the rule. Press to return to the parent rule. Since all rules are stored by reference, the capitalization of a rule name is set when the rule is initially entered, it cannot be changed after this. Whenever the name of a rule is changed (by editing it), all references to it are - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 52 - automatically updated. The editor will not allow the name of a rule to be changed to one which exists already, since it can't determine which rule is referred to. 4.4.3 Entering Screens A screen can be one of five types, [Dialg], [Dsply], [Help], [Menu] or [Print]. The meanings each of these modifiers is explained in the chapter on the screen designer. As with rules, the name of a screen can be changed and will be updated automatically in the screen file as will all references to it in the application being edited. As before, the new name cannot be one which already exists. To enter a screen, press or when hiliting the name of the screen in the edit window. If the named screen does not exist in the screen file already, then you will be prompted to select a screen type from a pop up menu. Because the screen designer is a major and large feature in RExL, it is documented in a chapter of its own. 4.5 Editor Lists At all times, the editor maintains lists of all entities defined within RExL. These are the lists of used and unused rules, used and unused screens and variables. Most of the lists have `hot-links', or special keystrokes which produce lists specific to the item hilited in the first list. The following three subsections tell how these lists are used. When a list is activated, a window, the width of the screen is displayed. The window extends to the second last line of the screen if there are enough elements to fill it, otherwise it sizes itself to produce a window large enough to hold all items. If all the elements cannot be displayed, a scroll bar will be displayed on the right hand edge of the list. The key can be used to move the window using the arrow keys while the contents of the window may be written to a file or the printer using the keystroke. All lists containing rules have a hot-link tied to the key. When this is pressed, the editor will quit the list and enter and expand the definition of the hilited rule. This keystroke is present in the normal and unused rule lists, the screen list, and all rule reference lists. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 53 - If a list is terminated by pressing , the last hilited item in the list will be pasted into the scrap buffer. Terminating the list any other way (say by pressing , , and so on) will not alter the contents of the scrap. 4.5.1 Reference List The reference list of a rule is the list of the rules which reference, or call, the rule currently being edited. The only hot-link in the reference list is the key, used to enter a rule's definition. Reference lists are available in the screen list, the rule list and the variable list. All reference lists are generated by pressing . The keystroke can also be used to generate the list of rules which call the current rule. This list performs the same operations as the generic rule reference list above. 4.5.2 Rule List The rule list is the most commonly used list of all and it is for this reason that it is attached to the keystroke of or . The rule list contains two hot- links, the first is the link as explained above, and the second link, tied to , which generates the rule reference list, the list of rules which reference the hilited rule. 4.5.3 Screen List The screen list gives the names of all screens defined in the application and is generated by pressing or . This list includes both used and unused screens. This list has two hot links, the first tied to , generates a screen reference list, the list of rules which use the hilited screen. This reference list has the normal hot-link key of to enter a rule's definition. The second hot-link in the screen list is tied to : When pressed, the editor will immediately jump to the first occurrence of the hilited screen within the application. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 54 - 4.5.4 Unused Rule List The unused rule list gives the list of rules which are unused in the current application and is generated by pressing or . There are a few minor quirks which you need to be aware of when using this list. Firstly, the list will not contain rules which are used by unused rules but are unused elsewhere within the application. Secondly, rules which are recursive, or use the modified rules from deeper than the first call level of the rule will not be included. To clarify the last point, if a rule called Top Rule called a rule Second Rule which then called Top Rule, all of which were unused by the rest of the application, the unused rule list would not determine that neither Top Rule nor Second Rule were unused. On the other hand, if Second Rule did not call Top Rule, then Top Rule alone would be found to be unused and placed in the list. If you wish to remove unused rules from the application altogether, press (or ). The hilited rule will be removed from memory and `forgotten' by RExL. If there are rules which were only used by newly deleted unused rules, then these can be listed by exiting from and re- entering the list. To enter the definition of an unused rule, press when hiliting the rule. When you are finished editing the definition of an unused rule, press to return to the main rule. 4.5.5 Unused Screen List The unused screen list is generated by pressing and is much the same as the unused rule list, with the exception that screens which are used by unused rules are said to be used. Press or to delete the screen from the screen file. 4.5.6 Variable List The variable list, on and lists all variables defined within your application. When the list is active, the status line at the bottom of the screen will display the type of the variable and its dimensions, if the hilited variable is an array. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 55 - There is one hot-link in the variable list: Pressing will generate a list of the rules which reference the hilited variable. Note that the variable reference list does not list the rules which contain screens which reference the variable. As with all reference lists, you can go directly to a hilited rule by pressing from within the reference list. You can alter the size of an array variable from within the variable list by pressing when hiliting the array. The cursor will reappear on the variable status line in the first of the array's dimensions, where the value there can edited. By default, all arrays are dimensioned to a size of ten in all the array's dimensions. 4.5.7 Function List This list contains all internal RExL functions and is generated by pressing or . The arguments which the function requires are listed on the status line at the bottom of the screen. There are twelve abbreviations which are used for the twelve different parameter types which may be passed to RExL's function. Table 4.2: Function Parameter Abbreviations Abbreviation Meaning number Numeric expression string String expression variant Numeric or string expression arraynv Variable size string or numeric array array1v One dimensional string or numeric array array2v Two dimensional string or numeric array array3v Three dimensional string or numeric array arrayn$ Variable size string array array1$ One dimensional string array array2$ Two dimensional string array array3$ Three dimensional string array arrayn Variable size numeric array array1 One dimensional numeric array array2 Two dimensional numeric array array3 Three dimensional numeric array Press to get language help on the function currently hilited. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 56 - 4.6 Other Functions The editor has a number of other functions which do not easily fall into any of the categories listed before. These are given here. 4.6.1 Graphic Rule Display The graphic rule display, generated by pressing , lists the dependencies of rules upon each other in an easy- to-understand graphic format. When in the display, you can move the hilite bar up and down by in the normal way. Pressing will expand the currently hilited rule's definition while pressing will paste the name of the hilited rule into the scrap buffer. The easiest way to understand the graphic rule display is to look at an example. [Figure not available in disk manual] When the graphic rule display was called, the editor was in the main rule, the root of the application, so therefore the entire dependency tree will be displayed. In this case, the Main Program consists of three rules linked as follows: If First rule And Second rule And Restart the application In the graphic display, rules connected by AND's are linked by vertical bars, hence the bar on the extreme left of the display connecting these three rules. First Rule contains the following: If First sub rule of 1st rule And Second sub rule of 1st rule Or Or This sub rule of the 1st rule As with the main rule, the first two lines in the first and-block are linked by a vertical bar. When the display generator reaches an OR connector, it terminates the vertical bar and begins a new one. In the case of the First rule, there is only one line in the second and-block, so the vertical bar cannot extend beyond the current line, so it will collapse to give a horizontal bar. The same procedure - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 57 - applies to the Second rule which has the same format as the previous one. Normal rules are colored light gray, while recursive rule calls or rules prefixed with the BackTo modifier are hilited in yellow. In the example above, all rules are colored light gray, except for the third last rule and the final rule in the display, both of which are prefixed by BackTo and are therefore colored yellow. As with all lists, this can be printed to a file or device by pressing and entering a file name. 4.6.2 Miscellaneous keystrokes 4.6.2.1 Cut and paste Beginning with version 2.10 of RExL, blocks of text can be moved around in the editor using the concept of the line buffer. The line buffer operates in a similar way to the scrap buffer on the bottom line of the screen. To copy a block of text, it must be selected and then inserted into the line buffer. The keystroke is used to set the `anchor' point and further movements of the cursor keys will extend the block in the direction moved. When the desired block has been marked it can be deleted, or cut, to the line buffer by pressing or copied to the line buffer by pressing again. When the line buffer contains text, the triple bar character _�_, is placed at the left hand end of the editor status bar, just to the left of the normal scrap buffer. Text is copied to, or pasted from, the line buffer by pressing . The editor will not allow text to be deleted to the scrap buffer if the current rule exists already in the rule stack. 4.6.2.2 Editing keys places a blank line before the current line, pushing those lines after the current line, down one line. The connector on the line pushed down will change to OR, in line with the rules for connectors. will delete the current line, pulling all lines after the current line up one line. The line's connector - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 58 - will be changed if necessary. The more normal keystroke of performs the same function as will act in the same manner as . moves the hilite bar to the top of the screen, while moves it to the bottom of the screen or the last line in the rule, whichever is nearer. moves the hilite bar to the first line in the rule. 4.6.2.3 Other keys will attempt to terminate the editor and return you to DOS. If the file being edited has been changed since it was last saved, then you will be prompted to save the file. displays the DOS screen, as it was when the editor first started up. toggles a runtime breakpoint at the current line. The breakpoint will be signalled by a breakpoint character, �. will save the current application while will load a new one. runs the application and calls up the debugger, prompting the user to save the application if it has not already been done. runs the application without calling up the debugger. will enter the screen designer, popping up a screen type selection menu if the screen specified on the line does not already exist in the screen file. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 59 - Chapter 5 Screens in RExL 5.1 Introduction This chapter documents the screen designer and the capabilities of screens in RExL. Screens are an integral part of RExL as a whole and are used for input, output and dialog in general with the outside world. The documentation on the screen designer is divided up into two chapters, the first dealing with the different types of screens available and their specific purpose with the system, while the second deals with the specifics of using the screen designer to produce the screens. Any modifications to a screen in an application are written immediately to disk in the disk based screen file. This allows for screen files which can be arbitrarily large. However, if changes are made to the screen file, and in particular, if the position of a screen changes within the screen file, then the old backup copy of the application image on disk (the ".RXL" file) will not hold a valid copy of your application. The reason for this is that screens are stored in application image files using reference numbers. If a screen's position is changed within the screen file, then the reference number for the screen will be invalidated, and because of the algorithm for squeezing screens into screen files, other screens may be invalidated also. The upshot of this is that whenever a change has been made to a screen file, you should press from within the edit window to update the application image on disk. This is not strictly necessary, but if you live in an area with frequent power outages, a `dirty' power supply or just simply wish to keep a valid backup at all times, then you do it. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 60 - 5.2 Fields 5.2.1 Introduction A screen field is an area of the screen which has some special property or meaning when the screen is activated in the application. There are five different types of field, some of which are possible in only some types of screen. A table at the end of this section gives the legal and illegal combinations of fields and screens. All fields have certain properties associated with them which modify the behaviour of the field in some manner. The various properties are covered in the next few paragraphs. 5.2.1.1 Field Properties Fields have two colors attached to them. The first is the active color, the color in which a field will appear when it becomes the active field on a screen. The second color is the inactive color which is the color in which they will be displayed at all other times, when they are inactive. By default, all fields have the same active and inactive colors (except for menu fields where one color is the `reverse' of the other, and output fields, which can have no active state). The combination of foreground and background color of a location on screen is generally known as its attribute, to avoid confusion with the less precise term `color' which can be used to refer to the foreground color, the background color or the combination of both. All fields which can display changing information can be specified as left justified (the default), in which case the information to be displayed will be placed flush against the left hand end of the field, or right justified where the information is placed flush right. The justification mode can be selected from the field control menu. The controlling variable of all fields must be a proper LValue, except for output fields where it can be any valid expression. While the screen is being run by the runtime module, the values of the various fields is rigorously kept up to date by global recalculation of all field values. The result of this is that whenever a value is specified for a field, the value is stored immediately and all the expressions in the fields in the screen are recalculated. However, if an application contains a screen with a large number of fields, this recalculation may slow down the - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 61 - screen. To get around this problem, there is a recalculation flag attached to fields to specify whether that field should be recalculated every time. As with field justification, the recalculation state can be selected from the field control menu. In the screen designer, the different field types are displayed using special characters which are removed before display during execution. The following six paragraphs outline briefly the functions of each of the different field types and how they are displayed on screen in the screen designer. Where possible, the initial value of a field will be the value of the field's LValue upon entry to the screen. 5.2.2 Output Fields Output fields are the most common form of fields. They are used to output either string or numeric information at fixed positions and within fixed boundaries. For numeric output, the decimal precision of the output can be specified and defaults to zero places of decimals. Output fields are displayed on the screen using hash symbols, #. The output field expression can be any valid numeric or string expression. Note that string results are output without quotation marks unlike the debugger expression evaluator and watch facility. 5.2.3 Input Fields Input fields are used for input of string and numeric information. Like all other fields except output, the input field expression must be a proper LValue. Numeric input fields can have a decimal precision specified for input. By default, the precision is zero places of decimals but it can be altered via the field control menu. Input fields can be specified as being required, meaning that for strings a non-blank string must be entered, while for numbers, a non-zero number must be entered. Input fields are displayed on screen as a series of question marks, ?, extending to the width of the input area. 5.2.4 Toggle List Fields A toggle list field is a list of string constants through which the end-user can move by pressing or - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 62 - to go to the next, or or to move to the previous choice. There can be a maximum of 100 choices in a single toggle list. Toggle lists are preferable to string input where there are only a small number of valid strings which may be entered. Toggle list fields can use either numeric or string LValues. Toggle lists are displayed on screen as a series of piping symbols, |, extending to the width of the field. 5.2.5 Check Box Fields A check box is a field which only take on a True or False value. Check boxes are useful when you have to implement a boolean choice, for example: whether the user wants to back up some data. String and numeric LValues are valid expressions for check boxes. The value returned to RExL for a checked check box is 1.0 for a numeric LValue and "Y" for a string LValue, while an unchecked check box returns 0.0 to a numeric LValue and "N" to a string LValue. If the check box expression is of string type, then the initial character in the string is used to determine the initial value of the check box field. The characters "Y", "T", "y" and "t" are all taken to mean True and all others are taken as False. A check box is displayed on screen as an open square bracket followed by a space and a close square bracket character: [ ]. When a check box is checked, the space in the center will be replaced by a tick mark �. The value in a check box is toggled by pressing . 5.2.6 Radio Button Fields A radio button field is a vertical list of choices, one of which must be chosen (it is for this reason that the field is known as a radio button). This field type is used for input of information similar to that in a toggle list field. Radio button fields are displayed as a three character wide column, each line consisting of an opening parentheses followed by a space and a closing parentheses. The current choice of the radio button is denoted by a solid dot placed between one of the sets of parentheses: (). When activated, and are used to move to the previous member of the radio button list, while and are used to move to the next member. Alphanumeric keystrokes (letters and digits) bring the cursor to the - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 63 - first button whose label's initial letter matches the keystroke. Labels are considered to be to the right of the radio button list. Consider the following radio button list: ( ) First Choice ( ) Second Choice ( ) Third Choice ( ) Fourth Choice On entry the radio button will indicate the label First Choice. Pressing the letter `S' will bring move the cursor to the second choice, since the initial letter of the label is `S'. Pressing `F' once brings the indicator to the fourth choice, while pressing it again brings it back to the first choice. 5.2.7 Menu Fields Menu fields are the simplest type of field available in RExL and can only occur in menu screens. They are defined as retangular areas of any size. When in use, the user switches from one field to the next in the same manner as in input, check box, toggle list and radio button fields. As with radio buttons above, entering letters will move the hilite bar to the first field after the currently hilited one to contain the letter pressed in its uppermost and left position. Unlike the other field types, menu fields may contain other fields. You can thus create menus with variable items by placing menu fields over output fields which display the item values. If you so wish, you can place menu fields within one another to give a moving bar type display. Menu screens return a value to the LValue attached to that screen. Internally, the LValue is stored as the first field in the menu screen and can only be changed when you are entering the screen designer, and not from within the screen designer itself. 5.3 Screen Types There are five different types of screen, each designed for a specific purpose. As explained in the Language chapter, - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 64 - each screen has an associated modifier which instructs RExL what to do with the screen when it encounters it in the application. Table 5.1: Screen Types Abbreviation Used for [Dialg] Basic input and output [Dsply] Output with pause [Help ] On-line user application help display [Menu ] Menu choice display [Print] Hard copy output Because modifiers are attached to individual lines rather than to the screens per se, a single screen can be used with more than one modifier. A typical example is a results output screen which can be displayed as a dialog screen, using the [Dialg] modifier and then printed as a print screen using [Print]. As noted above, not all field types are valid in all screens. The following table lists the valid combinations of field types and screen types. Table 5.2: Valid Combinations of Screen and Field Type Output Input Toggle Check Radio Menu Dialog Yes Yes Yes Yes Yes Menu Yes Yes Print Yes Help Yes Display Yes If you try to use a field in a screen which does not support that field type, you may get spurious results. As noted above, menu screens store their LValue in the first field in the screen, thus if you try to convert a non-menu screen to a menu screen, the menu's LValue will become the expression entered for the first field in the non-menu screen. In general, you should only mix screen types which have the same field types available. The next five subsections give details on the use of each screen type. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 65 - 5.3.1 Dialog Screen The dialog screen is the most used of all the screen types. It is the only screen which can contain numeric and string input, check boxes, radio buttons and toggle lists. Input starts from the top of the screen and proceeds to the right and down the screen. When in the screen designer, pressing displays the field sequence number of the field underneath the cursor. The sequence numbers are updated whenever a field is moved, created or copied. , and are used to move forward one field and and to move back one field. If there is a field directly above and touching the current field, then will move to that field, instead of a field to the right of the upper field. works in the same way. This makes block areas of input more intuitive to use. To terminate the dialog screen, press when the final field on the screen is active, or from any field. In numeric and string input fields, moves the cursor to the right hand end while moves to the left hand end. and move the cursor one word to the left and right respectively while undoes any changes to numeric and string input areas. If there are a large number of fields on the screen, then you may want to turn off automatic field recalculation to speed up processing of the screen. If there are any string or numeric input fields which are defined as being necessary but are not filled (non-zero for numeric fields), then a message to this effect will be displayed at the bottom of the screen and the missing field will be filled with X's which are removed with the error message when a key is pressed. 5.3.2 Display Screen Display screens are used to display information and to pause for a keystroke. This is to get around having to use a dialog screen with no active fields in it followed by a KBread() statement. The keyboard buffer is not emptied when - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 66 - this screen type is used, so you may need to precede the screen with a KBclear() statement. 5.3.3 Help Screen Help screens are used to implement context sensitive help during screen dialog. The number of help screens available to the user is not limited, although there can only be one help screen available at any one time. Whenever the runtime module encounters a help screen, an internal variable saves the name of the screen, then any subsequent keystrokes will cause this screen to be displayed. When the help screen has been displayed, RExL waits for a keystroke and then restores the contents of the screen as they were before was pressed. Once a screen has been saved as the current help screen, that screen will remain current until the next occurrence of a help screen. 5.3.4 Menu Screen Menu screens return a value to a numeric variable attached to the screen and can be used to implement block menus. Menu fields, which can only be used in this type of screen, can be of any size and may be nested inside one another unlike other field types. When a menu field is defined, the field's inactive color is set as described above but the field's active color is set to the `reverse' of the inactive color (for the computer literate, the active color is xor'ed with 7Fh to generate the reverse attribute). This is done so that the end-user of the system can tell which menu field is currently active. When a menu area has been defined on screen, a vertical line of piping symbols, |, is placed on the left hand and right hand sides of the area. When the menu is active on the screen, the piping symbols are replaced by blanks, to give a margin one character wide at either end of the area. When in use, the keys of , , and may be used to switch between menu fields in the normal way. As with the radio button field as explained above, pressing letters will move the active menu to the field whose first character (starting from the top left of the field and moving right and down) matches the keystroke typed. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 67 - If there are no menu fields in a menu screen, then the screen is displayed and execution continues without pause. As mentioned above, the first field in a menu screen is reserved for the menu screen's LValue. you should bear this in mind when trying to turn a menu screen into another type of screen (or vice versa). 5.3.5 Print Screen Print screens are used to send output to the printing device attached to your computer, which by default is the DOS file PRN file. This default can be changed by using the OUTPUT() command. A print screen may only contain output fields. Although RExL has no intrinsic support for printer effects such as italics, bold and so forth, you can send control sequences to the printer by using output fields which output the required characters. When RExL is printing a screen, it omits all lines containing spaces from the bottom of the screen, to avoid having large blank spaces in the printout. If you want to have print screens of fixed lengths, then you should place some nonblank character at the final line of the screen. For example, if you wish to print out labels of fixed height of (say) 9 lines, irrespective of the contents of the screen, then you should place some unprintable but nonblank character on the final line. The tab character, CHR$(9), is ideal for this and could be placed in its own output field on the last line of the label, or in the inter-label space. 5.3.6 Subscreens Subscreens are identical in function to ordinary screens, the only difference being that they do not occupy the full size of the screen. Subscreens are slightly cumbersome to define: By default, when the screen designer is asked to design a new screen, it assumes that the full screen is required. To get around this, a temporary screen (which will be dumped later) must be created and then the subscreen designed and saved as a block using the !Save! option in the block menu. The procedure to define a subscreen is as follows. Type in some temporary and unique screen name into the editor and press to select the screen type. The screen can then be designed as normal. When the design has been completed, - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 68 - the area of the subscreen can be marked out and saved to disk as the appropriate screen type. As this point, the screen designer can be terminated and control returned to the editor. Since the screen was not saved, the line will have reverted to being a rule which can then be deleted, since it was only temporary anyway. The subscreen saved from within the screen designer is now present in the screen list and can be inserted into the application listing as a normal screen. To force the screen type, the screen designer will have to be re-entered by pressing on the screen name and by selecting the appropriate screen type. If changes are made within the screen designer to a previously defined subscreen, then upon exit or saving of the screen, the screen designer will ask if the screen is to be saved at its previous size or at full screen size. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 69 - Chapter 6 Using the Screen Designer 6.1 Starting the Screen Designer The screen designer is fully integrated into the editor and can be accessed through the key. Before you can enter the screen designer and create a screen, you must supply a screen name for the screen so that it can be entered into the screen file on disk immediately. Once a new screen name has been entered, the screen type must be defined using the screen type menu on . This is a five item pop-up menu which lists the five different screen types. The items are listed in the order in which they are most commonly used. 旼컴컴컴컴컴� � Dialog � � Menu � � Print � � Help � � Display � 읕컴컴컴컴컴� The screen type is selected in the normal manner by using the up and down arrow keys and pressing . When a screen has been saved and the screen designer terminated, the normal editor screen will reappear and the screen name previously entered will be prefixed with one of the five screen modifiers as described above. The action of the key is slightly different when applied to a line containing the name of a screen and the type of the screen as reported by the line's modifier. In this situation, the screen designer is activated directly without going through the screen type menu. In order to change the type of a screen (for example from a display screen to a print - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 70 - screen), you must enter the name of the screen with no modifier and then press . Once the line modifier has been entered, the screen designer can be reactivated by pressing on the screen name, since the editor knows that this line refers to a screen and not a rule. If the menu screen type has been selected from the screen type menu, a dialog box will be displayed prompting for the menu variable (which can be any proper RExL LValue) associated with that screen. As explained above, when the menu screen terminates, the screen's menu variable will be set to the field number of the field which was current when was pressed. When the menu variable has been entered, the screen designer will start. When the screen designer is entered for the first time, the screen will be filled with the half-tone character (ASCII 177) colored in light gray on a black background (unless the `Print' screen type was selected, in which case the screen will be blank). The the cursor will be in the top left hand corner of the screen and screen designer is now ready for input. If there is a default screen defined (through the Edit|Default screen menu option) then the contents of the screen will be loaded automatically. If the screen designer is started with a previously defined screen, the screen designer will remove fields which would be invalid in the newly chosen screen type. For example, if a screen which was previously of type `Menu', and it were then opened as a `Dialog' screen, then the menu variable and the menu fields would be stripped from the screen. This feature should be borne in mind when saving screens. In general, cross-type screen translation should be avoided for this reason. 6.2 Basic Design The cursor is moved in the screen designer using the standard arrow keys , , and . In addition to these keys are the following: - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 71 - Table 6.1: Screen Designer Cursor Keys Key Moves cursor to start of line to end of line to top of screen to bottom of screen left one word right one word to top of screen to bottom of screen to top left hand corner of screen to bottom right hand corner of screen right ten characters left ten characters to beginning of line The action of the key is slightly more complex than simply moving to the start of the next line: If there is a box character on the next line underneath and to the left of the cursor, then the cursor will be placed on the right hand side of the box character. This behaviour makes it easier to enter text in boxes on the screen. 6.3 Fields in the Screen Designer The screen designer supports the use of six different types of fields as explained in the previous chapter. In general, a field definition can be initiated by pressing and the initial letter of the field type which you wish to define (for example output fields are attached to ). A field definition menu is attached to , from where you can select the field type to define, if you can't remember the different field types. When defining a field, the area marked out on the screen is painted in `reverse' colors to hilite it against the background. The location on screen where the field definition was initiated acts as an `anchor' point which remains fixed while the field is defined. Initially, the cursor is placed on the anchor point and can be moved about the screen using the arrow keys plus the four other cursor keys , , and . is used to terminate the field definition. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 72 - The menu field is the only field type which can be of arbitrary size so in all other field type definitions, the movements of the cursor are limited to avoid creating improper fields. The following table lists the valid sizes of fields: Table 6.2: Valid Field Sizes Vertical Movement Horizontal Movement Output Fixed height of one Yes Input Fixed height of one Yes Toggle Yes Fixed width of 3 Check Fixed height of one Fixed width of 3 Radio Yes Fixed width of 3 Menu Yes Yes When the field has been defined, a dialog box will appear (not applicable to menu fields) into which the expression associated with that field is entered. While in this dialog box, you are free to use the scrap buffer as normal, even though it is not displayed. The function and variable dictionaries are also available. Every field on the screen has a field number associated with it. This number codes for the order in which the fields are to be evaluated when the screen is run by the runtime module. The fields are numbered sequentially from zero, increasing moving to the right and then down the screen. This behaviour is compatible with the IBM- and MicroSoft- defined CUA standard for user interfaces. Whenever a field is created, moved or deleted, the screen sequencing numbers are recalculated, this may cause delays of the order of a half a second or so on XT-class machines. In the current release, there is no way to alter the sequencing order of fields in the screen. In any one screen there may be up to 128 fields. Beyond this limit, the amount of time required for processing the fields becomes noticeable. It should also be noted that any screen which uses more than 128 fields will be cluttered and should be redesigned to use less fields. The methods for entering the various fields are presented in the next six sections. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 73 - 6.3.0.1 Output is used to define an output field. Output fields can be up to eighty characters wide, the width of the screen, and are one character in height. Only horizontal movement is permitted while defining an output field. When the field has been marked out, a dialog box will appear prompting for an output expression. This can be any valid RExL expression and it will be syntax checked before it being accepted by the designer. When a valid expression has been entered, the marked area will be replaced with hash symbols, #, to denote an output field. 6.3.0.2 Input is used to define an input field. Input fields can be up to eighty characters wide and are one character in height. The input expression must be a properly formed LValue. As with output expressions, the designer will not accept an improper expression. Input fields are denoted by question marks, ?. 6.3.0.3 Toggle is used to define a toggle field. These fields can be between seventy seven characters and six characters (inclusive) in width and are one character in height. The toggle expression must be a proper LValue. You can have up to one hundred choices occupying up to four thousand characters of storage in an individual toggle choice field. When the field has been defined, two dialog boxes will appear, the upper one for the toggle list LValue and the lower for the list of choices. A field LValue, which can be either string or numeric, must be entered before the individual choices can be. As before, you are not permitted to enter an invalid LValue. When a valid one has been entered, the cursor will move to the second box, labelled Choices. The second box will be of the same width as the toggle list field, so that strings which would not fit in the field are not allowed. The strings are entered in the order in which they are to appear in the field when it is activated. An individual toggle list item can be deleted by pressing or . The list entry is terminated by pressing on an empty list item and it is for this - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 74 - reason that empty toggle list items are not allowed. The cursor can be toggled between the two windows by using and . When the field has been defined, the marked area will be replaced by a series of piping symbols, |. 6.3.0.4 Check is used to define a check box field. Since this field can have only one size of three characters wide by one high, the LValue dialog box will appear immediately prompting for an LValue which may be either string or numeric in type. When the LValue has been entered, the marked are on the screen will be displayed as a set of square brackets separated by a tick, [�]. 6.3.0.5 Radio is used to define an radio button field. Radio button fields have fixed widths of three characters but may be as high as twenty-five characters, the height of the screen. The radio button LValue must be a numeric expression and not a string expression. When the field has been defined, the marked area will be replaced by a vertical block of sets of parentheses separated by the center dot character. 6.3.0.6 Menu is used to define a menu field and can only be used in menu screens. Menu fields can be of arbitrary size and may be nested within one another, unlike all other field types. Since, in menu screens, the menu expression is entered when the screen itself is entered and is therefore constant for all fields, there is no menu expression dialog box associated with menu fields. So, when the menu area block mark has been terminated by pressing , the vertical edges of the block will be marked with piping symbols, |, and control will return to the main screen designer directly. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 75 - 6.4 Block Operations Blocks are rectangular areas of the screen which can be defined and then used for various operations. A block is marked by pressing and then moving the cursor in the same manner as that used during field definition. For those more familiar with Sidekick and the Borland-type editors, the keys and may be used to start and end block definition. When a block has been defined, the block menu, which contains nine items, will appear in the top left hand corner of the screen (unless it has been moved). There are nine separate operations selectable from the block menu which may be carried out on marked blocks, and these are covered in the next nine sections. Note that if the block contains a portion of a field, then certain operations are not allowed since they would have no meaning when applied in those circumstances (for example, moving and copying portions of a field). If these are attempted, then the screen designer will display an error to the effect that the area crosses fields. Once a block has been defined and some block operation carried out upon it, it may be re-marked for further operations by pressing . Typically, this is useful when a box has been drawn which then needs to be painted. 6.4.1 Block Painting This option is used for setting the foreground (ink) and background (paper) colors of the defined block. When this option is selected, the following paint box appears: [Figure missing in disk manual] The color of the foreground is altered using the and keys and is tracked in the left pane of the paint box window by a gray square. The background color tracked in the right hand pane with two center dot characters and is changed with the and keys. The row of `x' characters at the bottom of the paint box display the combined foreground and background colors. On the EGA, VGA and most CGA systems, the screen designer can make use of the flash-intensity bit. This allows the use of sixteen background colors instead of eight, at the expense of flashing. This bit can be toggled on and off by pressing - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 76 - . If the system which the editor is running on supports this feature, then the lower eight colors in the right hand pane will be `brightened'. These can then be selected in the same manner as ordinary background colors. Note, however, that some early CGA adapters do not support this, with the result that what should have been displayed in intense background will in fact be displayed as flashing. The keystroke can be used anywhere within the screen designer and is not limited to the paint box. If the block area being painted covers a field or part of a field, then the attributes of the field will be updated to the new colors. As with all windows in RExL, the paint box can be moved by pressing the key, if it obscuring something. When the desired combination of foreground and background colors has been reached, will terminate the paint and make the colors permanent. 6.4.2 Align When the align option is selected, the marked area will be moved from its old location and placed at the horizontal and vertical center of the screen from where it can be moved using the normal arrow keys. Pressing will make the alteration permanent. In all cases where blocks are moved from one location to another in the screen designer, the attributes of the screen underneath the original block are left untouched and are copied, along with the character information inside the block, to the new location for the block. It is not possible to align blocks which contain portions of a field. 6.4.3 Box The box option is used to draw boxes around the marked area on screen. On selection, the following box menu appears: [Figure not included in disk manual] The first option in the menu selects whether the box is to overwrite the contents of the box (but leave the fields inside intact) or whether the box is to overlaid around the edge of the area leaving the interior untouched. The option - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 77 - can be toggled by pressing on it. If the overlay option is selected, then, if possible, the box will link up with any boxes which impinge upon the marked area. To draw a box of a particular type, hilite a suitable border type and press . The box will then be drawn on screen. If the screen is destined for use with a printer (such as a print screen), then, unless all printers which may be used with the system support them, the first five box edge types should not be selected, since few printers support the line draw characters in their native mode. When defining a block for use with this option, it is permissible to include portions of a field within the block, although those parts of the box which would cut the fields are removed. Alternatively, boxes can be drawn directly by using the keystroke. When this keystroke is pressed, the screen designer again enters its block-define mode and the extent of the box is drawn on the screen. When the desired box has been drawn, it is selected using and the box type selection menu appears as before. 6.4.4 Delete The delete option is used to delete a marked block. As with the align and move options, the attributes of the originally marked area remain unaltered after the operation. Any fields which are fully within the block are also deleted and the remaining fields are re-sequenced to take account of the new field layout. While the block is being marked, the , and keystrokes may be used to delete the block immediately, without having to go through the block menu. 6.4.5 Move The move option is used to move a marked block. The marked area cannot cross any fields since attempting to move a portion of a fields has no meaning. When the option has been selected, the cursor will disappear and the screen designer enters its block move mode. The block may be moved using the , , and keys. Pressing will terminate the move. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 78 - If the area where the block is to be placed contains any fields, then the fields will be deleted and the field sequence will be regenerated. If the area crosses any fields, then the move will be terminated with an error. When the block has been placed successfully, the character information is removed from the old location of the block while the attributes are left as they are. 6.4.6 Copy The copy option is substantially the same as the move operation above, with the single difference that when the destination is selected, the contents of the original block are left unchanged and new fields are created in the destination. If there are a large number of fields on the screen, then care should be taken that the limit of 128 fields is not reached while copying blocks. If it is reached, then an error to this effect will be displayed and the copy terminated with the fields remaining to be copied being left uncopied. 6.4.7 Fill The fill option in the block menu is used to fill a defined area with a particular character. When the option is selected, the character fill selection box appears on the screen, again, in the top left hand corner of the screen unless it has been specifically moved. [Figure not included in disk manual] The character to fill the block is hilited in the fill selection box in yellow foreground on a magenta background. The normal arrow keys are used to move the selection bar around the list while and are used to move from one group of 64 characters to the previous and next pages respectively. is used to select the character to fill the defined block with. If the block contains any fields, then these will be redrawn when the fill operation is finished. The foreground and background colors are left unchanged by filling the block. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 79 - 6.4.8 Save This option is used to save a block to the screen file. This feature is mainly used for creating pop-up menu type displays. When this option is selected, a dialog box will appear, prompting for a name under which to store the block in the screen file. When a name has been entered, the screen designer checks to see if that name already exists in the screen file. If the name is unique, then the block is saved immediately, otherwise, a yes/no menu will appear, asking whether the previous version of the screen should be overwritten with the new one. Selecting the `yes' option from this menu will cause the marked block to be written to the screen file in place of the old one. Once the screen has been saved, it can be read and modified like any other full sized screen. Detailed information on the use of small screen blocks can be found in the section on sub-screens further on in this chapter. 6.4.9 Under shadow The final option in the block menu is used for drawing `shadows' which appear `underneath' marked blocks on the screen. This option is most commonly used for hiliting some important information in a box on the screen by making the box stand out against the background. The undershadow effect is achieved by painting the area to the right of and below the marked block in a light gray foreground color on a black background. The undershadow effect works best when applied on a bright background. Overuse of this effect should be avoided since it loses its emphasis easily. 6.5 Sub-screens Sub-screens are created using the save block procedure as described in the previous section. They are mainly used for creating pop-up menus and other types of pop-up queries. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 80 - The easiest method to create a pop-up sub-screen is as follows: Enter the screen designer at the screen where the pop-up will appear and create the pop-up, mark the area and then save it as a block. Exit from the screen designer, but do not save the parent screen permanently when requested to. Return to the location in the listing where this pop-up will be used and then call it as a normal screen. When the runtime module runs the saved block of screen, it will only load that portion, leaving the rest of the screen as it was before the screen was called, thus creating the effect of a pop-up screen. The screen designer treats sub-screens in almost exactly the same manner as normal full-sized screens, the only differences being as follows. Firstly, upon entering the screen designer with a sub-screen, the sub-screen will be loaded at the same co-ordinates on the screen as it was saved from, while the rest of the screen will be painted with the normal background half-tone character. Secondly, when exiting from the screen designer, instead of the normal `Do you want to save the screen ?' prompt, the prompt `Screen was originally smaller. Save as:' will appear. This menu has three options in it: Original area, Full screen, and Return to editor. The first option will save the original screen block to disk, the second saves the entire screen to disk in place of the original sub-screen, while the final option quits the screen designer entirely and return control to the editor without saving the screen. A minor point to note is that attempting to print sub- screens will not produce the expected results, since the rest of the screen currently on display will be included with the output. 6.6 Field control menu has two uses in the screen designer, which one is used depends on whether the cursor is over a field or not. When the cursor is placed on a field, will bring up the field modification menu, described in this section. When the cursor is not over a field, then will pop up the field type definition menu, described in the next section, listing the six field types from which one can be chosen. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 81 - The field control menu, popped up by a keystroke of while the cursor is hiliting a field, controls the properties attached to that field. The field control menu is slightly different for each field type on account of the differing requirements for each. In total, there are nine properties which may be attached to each of the six different field types as indicated as follows: Table 6.3: Valid Field Attributes Input Output Toggle Check Radio Menu Active color Yes Yes Yes Yes Yes Yes Inactive color Yes Yes Yes Yes Yes Delete Yes Yes Yes Yes Yes Yes Expression Yes Yes Yes Yes Yes Recalc Yes Yes Yes Yes Yes Justify Yes Yes Yes Width Yes Yes Yes Yes Necessary Yes Precision Yes Yes Validate Yes The field control menu for a particular field type consists of the options ticked in the table above underneath the fields. The next nine subsections give the meanings of the items in the field control menu: 6.6.0.1 Active color The active color of a field is the attribute which is used to color the contents of a field when that field is active. All fields, except output fields, have active colors. When this option is chosen from the menu, the standard paint box appears and the field attribute can be selected from this. 6.6.0.2 Inactive color The inactive color of a field is the attribute which is used to color the contents of a field when that field is inactive. All fields, including output fields, have active colors. When this option is chosen from the menu, the standard paint box appears and the field attribute can be selected from this. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 82 - 6.6.0.3 Delete This option will delete the hilited field from the screen and perform a screen field resequencing. Pressing while hiliting a field in the screen designer has the same effect as choosing this option. 6.6.0.4 Expression The expression attached to a field can be edited when this option is selected. The edited field expression will be checked for correct syntax before it can be accepted by RExL. When the cursor is hiliting a field, can be used as a shortcut keystroke for this function, while will simply display the field expression on the bottom of the screen. For toggle fields, the choices may also be altered. 6.6.0.5 Recalc Under normal circumstances, the runtime module will automatically recalculate all fields in a screen whenever the contents of one field are modified. If there are large number of fields in the screen, then this may slow down the operation of the screen designer. Toggling this option on and off will enable and disable the automatic recalculation of the hilited field. 6.6.0.6 Justify Normally, the contents of fields are left justified, that is, placed flush against the left hand end of the field. This option can be used as a toggle to toggle the placement between the left and right ends of fields. Note that during numeric input in input fields, the number is always justified right. When input is finished in the field, the result will be justified as specified by this flag. 6.6.0.7 Width The width of a field can be altered using this option. When it is selected, a block will appear of the same size and shape of the field. This can then be changed in the same manner as ordinary block definition. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 83 - When a suitable size has been chosen and has been pressed, the screen designer will check to ensure that the new field does not cross any earlier fields. 6.6.0.8 Necessary String and numeric input fields my be defined as being `necessary' for the proper completion of the screen. If this flag has been set, then a zero value, for numeric fields, and an empty string value, for string fields, will not be allowed as valid input. The runtime module will hilite the unfinished field in red, fill it with X's and post an error message on the bottom of the screen and return the end-user to the field. 6.6.0.9 Precision Numeric input and output fields can have an optional decimal precision supplied. This will be the number of decimal places to be displayed or input when the runtime module processes the field. 6.6.0.10 Validation Numeric and string input fields may be validated as date and time strings by toggling the validation type between `None', `Date' and `Time'. If the user enters a string, then it will be checked for validity by the runtime module. If the string is found to be invalid, then execution will not proceed until a valid string is entered. The format checked will be the format current on your machine, or that set up by a call to the DTformat() command. Note that the null date string, "00/00/0000" is considered to be a valid date. If you want to filter out this date, then you should set the `necessary' flag. 6.7 Miscellaneous Functions 6.7.0.1 Changing Field Types The key combinations noted above for defining fields also have another use in changing a field from one type to another. For example, pressing when the cursor is hiliting an input field will change that input field to an output field. The exact procedure is as follows: When the - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 84 - key combination is pressed, the screen designer looks to see if the cursor is placed over a field, if it is, then the field type is changed to that specified by the keystroke and the field definition routine is called. The width of the field can then be changed. Pressing will terminate the width definition and bring up the field expression dialog box (or both of them if the new field is a toggle field). The field changing facility is most useful when changing a screenful of input fields to output fields. 6.7.0.2 Field Utility Keys is used to edit a field expression, when the cursor is on a field. This function is placed on a special key of its own, since it is used regularly. If the cursor is not over a field, then this key has no effect. The keystroke can be used to display the expression associated with the cursor field. When this keystroke is used, the expression is only displayed and cannot be modified. is used to delete the field underneath the cursor. As with , this keystroke has no effect if there is no field underneath the cursor. The keystroke is used to display the screen status on the bottom line of the screen. The status display contains four items of information: Displayed from left to right, these are the current cursor position in (x,y) format with (0,0) at the top left hand corner. The next two sets of coordinates give the size of the currently defined block (if no block has been defined, then the full screen is used). The `Fields' display gives the number of fields defined in the screen (the second digit) while the first digit gives the sequence number of the field underneath the cursor, or 0 if there is no field there. The type of the hilited field is displayed beside the sequence number. The final display gives the amount of free memory left to the screen designer. For proper operation, this figure should be above 10k. 6.7.0.3 Line Drawing The line drawing feature of the screen designer is used to draw lines on the screen using the IBM ASCII characters between 179 and 218 inclusive. When is pressed, the designer enters line draw mode and the cursor is backed by a - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 85 - `reverse' attribute block to emphasise the fact that the screen designer has changed mode. When is pressed, the line draw menu appears in the top left hand corner of the screen: [Figure not included in disk manual] The first option in the menu toggles between overlay and overwrite modes (explained below) while the other options specify the type of line to be drawn. The normal arrow keys and , to move right, are used to move the head of the line about the screen. When drawing a line, the character underneath the cursor is not updated until the cursor is moved. This needs to be done because the exact character required depends on the next direction of travel of the cursor. The line draw mode can operate in one of three modes: o Overwrite mode, where the line being drawn does not link up with any previous line on the screen. o Overlay mode, where the line does link up with lines already existing on the screen. Note that not all combinations of line draw characters can be displayed using the ASCII character set, in these cases, the current line draw type will take precedence over older lines. o Delete mode, where the character underneath the cursor is deleted. This option is most useful for deleting old lines from the screen. The key is used to toggle between overlay and overwrite modes, with the cursor being an underline in overlay mode and a half-box in overwrite mode. The key is used to toggle delete mode on and off. In delete mode, the cursor is placed in the upper half of the character box. While the line is being drawn, the shape of the line being draw may be changed using the key in combination with the digits 1 to 4. The following table summarizes the keystrokes valid in line draw mode: - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 86 - Table 6.4: Keys in Line Draw Mode Move up Move down Move left , Move right , Terminate line draw mode Toggle overlay and overwrite mode Toggle delete mode Set horizontal line emphasis to one line Set horizontal line emphasis to two lines Set vertical line emphasis to one line Set vertical line emphasis to two lines 6.7.0.4 Other Editing Keys , used to delete lines, has two functions. When it is first pressed, it deletes all characters and fields to the left and right of the cursor up to, but not including, the nearest box characters. If it is pressed again immediately, then the entire screen line will be deleted from the left edge to the right edge and the lines underneath will be pulled up by one character. Note that must be pressed twice in succession with no intervening keystrokes for the entire line to be deleted. is used to delete the character underneath the cursor. All characters up to but not including the next box character to the right of the cursor will be move one character to the left. If is pressed over a box character then the box character itself will be deleted. deletes the character to the left of the cursor and moves the cursor one character to the left, moving all characters to its right, up to but not including the nearest box character, one character left. 6.7.0.5 Lists in the Screen Designer The editor's three most commonly used lists are also available in the screen designer. These are the variable list on and , the rule list on and and the screen list on and . The hotkey reference lists which are available in the main editor are not available when these lists are requested in the screen designer. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 87 - 6.7.0.6 Miscellaneous Keys The keystroke will save the screen to the screen file. If the screen was originally a sub-screen and not a full sized screen, then the prompt `Screen was originally smaller. Save as:' will appear with a three option menu, instead of the normal `Do you want to save the screen ?' prompt. This feature is explained in the section on sub- screens. and are used to exit from the screen designer and to return to the main editor. As before, if the screen has been altered, then you'll be prompted to save it before continuing. All keystrokes greater or equal to the space character and less than or equal to an ASCII code of 255 are placed directly onto the screen. If insert mode is active, then all characters to the right of the cursor will be moved one character to the right, with the rightmost character being lost. If insert mode is not active, then the character underneath the cursor will be deleted. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 88 - - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 89 - Chapter 7 The Runtime-Debugger 7.1 Introduction This chapter covers the functions and capabilities of the debugger module in depth (when we refer to the debugger in this chapter, we mean the runtime-debugger module as a whole). The interface used in the debugger is much the same as that in the editor, so you shouldn't have much trouble using it. The debugger-specific keystrokes are largely the same as those used by the Borland integrated debuggers, so if you have used those, then a quick read through this chapter should be sufficient. 7.2 Debugger Basics The debugger is started by typing `rexlrd' at the DOS prompt. Contrary to the requirements of the editor, you must supply a file name on the command line. If you omit the file name, then a few lines of command line help will appear. In the current release, there are three command line parameters which can be supplied to the debugger, these will be covered at the end of the chapter. Unlike the editor, the debugger does not read or generate a configuration file. The debugger can run in either of two modes: The first is run mode, in which the application is executed without stopping between rule calls, statements and screens. The second mode is debug mode, in which the full screen debugger controls the execution of the system. Debug mode is used if you select the option Debug application from the Run menu in the editor, or if you press while the application is executing in run mode. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 90 - There are a few terms which you need to understand before you continue with the rest of this chapter. These are explained here: o Step and Trace: An application is stepped or traced when the runtime portion of the module gains control of the application and executes some portion of it. o Watch: A watch is an expression, visible in the watch window at the bottom of the screen, which is evaluated every time the debugger module is given control of application execution. When you enter debug mode, you will be presented with the main debugger screen (note that you can't have all the menus pulled down at once, as they are here! The dots and arrows indicate where the menu is normally displayed): [Figure not included in disk manual] The bar at the top of the screen has four pull down menus. In the same manner as the editor, these can be activated by pressing the left and right arrow keys to move from one to the next, and pressing the enter key to select the hilited menu. Press to return to the code window from the menus. To the right of the four menu titles, is the name of the RExL file which is currently being debugged. The third last line on the screen is the debugger status line, which has the same function and features as the editor status line in the editor. Underneath the debugger status line is the watch window (blank above) where watches are kept. On start-up, the watch window is one character high, but this will grow and contract as watches are added and removed. The bottom line of the display lists some of the short-cut keystrokes which can be used in the debugger. The Code Window is above the status line and displays the rule currently being executed. Cursor movement in the code window uses the same keys as in the editor. The four menus on the main horizontal menu bar have contents as follows: - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 91 - 7.2.1 File menu 旼컴컴컴컴컴컴컴컴컴컴컴커 � Return to editor � � OS shell � � Quit � 읕컴컴컴컴컴컴컴컴컴컴컴켸 The file menu has the following seven options: o Return to editor: This option will return control to the editor, loading the application currently being debugged. o OS Shell: If you want to run a DOS command, but do not wish to exit from the debugger permanently, choose this option to go into a DOS shell. While you are in the shell, you should not, under any circumstances, run any T&SR programs (such as Sidekick, ScrGrab and so forth), since these programs change critical area of the computer's memory which may cause it to crash unpredictably when you return to RExL. When you are finished in the shell, type `exit' at the DOS prompt to return to RExL. o Quit: This choice will quit from the debugger and return you directly to DOS, irrespective of whether you started the debugger from within the editor or not. 7.2.2 Debug menu 旼컴컴컴컴컴컴컴컴컴� � Watch � � Evaluate � � Run � � Step � � Trace � � Halt here � � Breakpoint � � Animate � 읕컴컴컴컴컴컴컴컴컴� All of the options in this menu are also available through hot-key short-cuts. When you become familiar with the debugger's keystroke map, you'll probably not need to use this menu. There are eight options in this menu: - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 92 - o Watch: This option, which is also available via the hot-key o or , controls the entry of new expression watches into the watch window at the bottom of the screen. The procedure for entering watches is covered in detail in the next section. o Evaluate: Selecting this option, also available through or , causes an expression evaluation box to appear. This is also covered in the next section. o Run: This choice will return the debugger to run mode and will not return control to the debugger, unless it meets a breakpoint or you press . Pressing is equivalent to selecting this choice. o Step: This menu choice is identical to pressing . o Trace: This choice is identical to pressing . o Halt here: This option, also available by pressing , will set a temporary breakpoint at the line currently hilited in the code window. When execution reaches the line, the debugger will regain control and the breakpoint will be cleared. o Breakpoint: This option (also on )sets a breakpoint at the line hilited in the code window. Whenever execution reaches this line, the debugger will regain control. o Animate: This choice (also on ) will cause the debugger to emit a trace instruction at variable intervals, so that the debugger appears to control itself. Pressing any key while animating will return control to the user. 7.2.3 Lists menu 旼컴컴컴컴컴컴컴컴컴커 � Rule list � � Screen list � � Unused rule list � � Unused screen list � � Variable list � � Function list � - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 93 - � Call stack � 읕컴컴컴컴컴컴컴컴컴켸 This menu gives you access to all the lists of entities which are defined the current application. Most of the lists have special `hot-links' to other, more specific, lists. These are mentioned briefly at the end of this subsection and covered in more detail further on. All of these lists are also available via hot-keys from within the main editor window. Consult the section on editor keys for more information on this. The lists run menu has the following six options: o Rule list: This list contains the names of all of the rules which are currently defined in your application. o Screen list: This list contains the names of all screens defined in the currently active screen file. o Unused rule list: This list shows all rules which, although defined in the normal way, are not actually referenced by the application. Pressing within this list will delete the unused rule from the application. o Unused screen list: This list gives all screens which are not referenced in the current application. As with the unused rule list above, press to delete the unused screen from the list and free up the space it occupies within the screen file. o Variable list: This list contains all variables. The status line at the bottom of the screen displays the type of the variable, whether numeric or string, and whether it's an array or a simple variable. o Function list: This list contains all the functions available in RExL. Press for help on the hilited function. o Call stack: The call stack is the list of rules which are currently executing. The most recent call is at the bottom of the list. The `Main Program' rule is always at the top of the list. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 94 - All the list windows are movable by pressing , using the arrow keys to position and pressing , or to terminate the window move. Note that all lists in RExL feature helix searching. You can also output the contents of any list to a file (or the printer) by pressing , as in DOS. If you terminate any of the lists by pressing , then the choice which you selected from that menu will be placed into the scrap buffer, ready for pasting using the keystroke. 7.2.4 Options menu 旼컴컴컴컴컴컴컴컴컴컴컴� � Load macros � � Save macros � � Beep off � � Function lower case � � Exploding windows off � � Screen swap: smart � � Repaint screen � 읕컴컴컴컴컴컴컴컴컴컴컴� The options menu controls various system parameters and features not directly connected to the editor per se. o Load macros: Any macro definitions you define in the editor may be saved to disk for later retrieval using this menu option. The macro file format is constant across the RExL product range, so that macros defined in the editor may be used in the debugger or in the database manager and so on. Macros are explained in more detail at the beginning of this chapter. o Save macros: This option allows you to save macros which can then be reloaded at some future time using the load option above. o Beep off: By default, RExL beeps whenever it encounters an error. This beeping can be toggled on and off by selecting this option. o Function lower case: By default, all functions in RExL are displayed in their natural case. This is that functions which are members of families are displayed with the first two or three letters capitalised, while the miscellaneous functions are - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 95 - entirely capitalised. This option is used to toggle between upper (or partially upper) case function name display and lower case. o Exploding windows off: In its normal state, all windows in RExL open instantaneously upon activation. This option can be used to make windows `grow' to full size on the screen. This is only a visual effect and has no effect upon the application. o Screen swap on: Whenever the debugger is stepped or traced, the debugger will swap its own screen with that of the application running underneath it. If your application does not access the screen, then you can toggle this option to `None' to disable the screen swap. o Alternatively, you can set the mode to `Smart', when RExL will check the line about to execute to determine if the line contains an expression which could change the screen. If this is so, then the screen will be swapped, but not otherwise. Smart screen swapping is the default screen swap mode. If, when screen swap is off, your application accesses the screen, the change will be lost when the debugger regains control of execution, possibly with a garbled screen. o Repaint screen: This option is used to restore the debugger screen after it has become corrupted. Corruption of the debugger screen happens when screen swap has been disabled during a screen access by the application. 7.3 Using the Debugger The familiar keystrokes of , , , and so on, are all supported in the debugger as they are in the editor. While designing the debugger, we have tried to strike a balance between its functionality and size. It is for this reason that, although the keystroke generates the rules list as in the editor, there are no hot-links to the other features, such as rule reference and so forth. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 96 - The following is a typical debugger screen: [Figure not included in disk manual] As with the editor, the status line (this time on the third last line) shows the amount of memory remaining free for the runtime module to use. To the right of this is the level display, showing the depth which the debugger has reached. There are two differences to the layout of rules in the code window. The first difference is the current line pointer character, ASCII 16. This points to the line which will be executed as soon as the runtime module regains control of execution. The line pointer character is placed between the line's modifier and the actual text of the line. In the example above, the line pointer points to the final line in the code window. In practice, this character will be colored yellow to make it visible above the background. The second difference is the character on the far left of the line. This character indicates the current logical status of the line, X, for False, � for True and ? for unknown. On start-up, all lines are assigned a value of unknown, but as the application executes, the lines' logical values are filled in. When a line is about to be executed, its status is set to unknown. Other than the differences from the editor noted above, the only features to be understood in the debugger are application step, trace and the function of watches and breakpoints. These are covered in the next four subsections. 7.3.1 Step When the application is stepped, the runtime module is given control of execution and it will run the line which was last hilited in the debugger's code window. RExL uses the keystroke to step. If the line was a statement, then it will be evaluated and the value returned will be assigned to the line's logical status as indicated by the character at the far left of the line. If the line was a rule, then the rule in its entirety will be executed and control returned when the rule has returned True or False to the caller. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 97 - If the line was a screen, then the screen will execute and return True. 7.3.2 Trace Trace works in the same manner as step does above, with one important difference: When you trace a rule, the debugger will expand the definition and place the debugger's hilite bar on the first non-blank line of the rule. or is used to trace a line. 7.3.3 Watch As explained above, a watch is an expression which is `watched' by both you and the debugger. The expression can be either string or numeric in type and is displayed in the watch window, underneath the code window. Watches are entered by pressing the key (or ). A dialog box appears, prompting for an expression to watch. The syntax will be checked and if valid, will be entered into the watch list. The format of the watch is simple: It consists of the expression entered, followed by a colon and a space, followed by the value of the expression you entered. If the cursor is placed over some alphanumeric symbol in your source, then that symbol will be entered in the dialog box. You can move the hilite bar to the watch window by pressing , although this will not be allowed if you do not have any watches in the watch window. When in the watch window, you can add new ones by pressing or as before. Watches can be deleted by pressing or or . Watches are more powerful (and dangerous) than they may at first seem: Since you are allowed to enter any expression as a watch, this may clearly include expressions like DBnext(), CLS() (and so on), functions which alter the status of RExL. Entering expressions such as these can have various unwanted side-effects in debugging sessions. The final point to note is that only those expressions which are visible in the watch window are actually evaluated at every cycle. You can have at most ten watches visible in the watch window at any one time. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 98 - 7.3.4 Expression Evaluate Expression evaluation is a `shortened' version of watching. It allows you to enter an expression and RExL will return the value of that expression either string or numeric. Evaluation, however, has one major difference from watching in that it allows you to enter a new value for an expression, if that expression is a valid LValue. [Figure not available in disk manual] When the expression evaluation box initially appears, the cursor will be in the Evaluate pane. If the cursor was placed on a word within the window, then that word will be pasted into the box. The expression which you want to be evaluated is then entered. The expression will then be syntax checked. If the syntax is not correct, then the you will be returned to the evaluate pane, otherwise the expression will be evaluated and the result displayed in the Result pane. If RExL has determined that the expression is a modifiable LValue, then the result of the expression will also be displayed in the New Value pane (whose border will change color), otherwise that pane will remain empty and the border color of the new value pane will remain unchanged. If the expression is an LValue, then you can press to bring the cursor to the new value pane where you can enter a new value for the expression. This new value can be any valid expression which returns a result of the same type as the initial expression. Again, this expression is syntax checked and evaluated and the result is assigned to the expression in the evaluate pane. 7.3.5 Animation You can `animate' the execution of your application by pressing . During animation, the debugger simulates the pressing of the trace key at a definable interval. When you press , a numeric dialog box appears, prompting for an animate delay, measured in tenths of a second. This value can range from 0, where there will be no delay, to 600, where there will be a delay of one minute between successive steps. - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 99 - Press any key to stop the debugger animating the execution of the application. 7.3.6 To Here The debugger can execute an application to the current cursor line, `to here', when you press . This feature is sometimes known as temporary break-pointing, since the effect is to place a breakpoint at the line and run the application until either execution reaches a breakpoint, the application terminates or you press : In any case, the breakpoint will be cleared. 7.4 Miscellaneous keystrokes moves the hilite bar to the top of the screen, while moves it to the bottom of the screen or the last line in the rule, whichever is nearer. moves the hilite bar to the first line in the rule. will attempt to terminate the debugger and return you to the editor, if the debugger was called from there. sets up a temporary breakpoint on the currently hilited line. and bring up the expression evaluation box. displays the start-up screen of the editor. toggles a breakpoint at the current line. The breakpoint will be signalled by a breakpoint character, �. animates the debugger. You will be prompted for an animation delay. and enter a new watch expression. Entity lists are (as in the editor) as follows: - RExL Version 2.11 Copyright 1992, The Software Loft - - Main Manual. Page: 100 - Rule list: on and Screen list: on and Unused rule list: on and Unused screen list: on Variable list: on and Function list: on and 7.5 Command Line Parameters The debugger accepts the use of a number of command line parameters. These are letters (preceded by minus signs, -, or forward slashes /) which alter some internal default of the debugger. The current command line parameters are as follows: o -d: The `d' parameter will cause the debugger to start up in debug mode, as if the user had pressed during loading of the application. This switch is passed invisibly by the editor to the debugger whenever the debugger is called via the Debug application option in the Run menu in the editor. o -e: The `e' option will return control to the editor when the debugger terminates. Whenever the editor calls the debugger, this option is silently passed to the debugger, so that the debugger will return to the editor when it terminates. o -k: This `k' option is used to tell the runtime module not to watch out for the two keystrokes of and , which are normally monitored. ( will interrupt the run module and relinquish control to the debugger while pressing twice will terminate the application.) - RExL Version 2.11 Copyright 1992, The Software Loft -