MAPL Micro-APL for the 6809 Revised: 30-Jul-90 Dunfield Development Systems ---------------------------- High quality tools for Embedded Development at low prices. https://dunfield.themindfactory.com Copyright 1983-2005 Dave Dunfield All rights Reserved MAPL USERS GUIDE TABLE OF CONTENTS Page 1. INTRODUCTION 1 2. CALCULATOR MODE 1 3. OPERATORS 1 4. USER VARIABLES 2 5. SYSTEM VARIABLES 2 6. USER DEFINED FUNCTIONS 4 6.1 EDITING FUNCTIONS 4 7. MAPL OPERATORS 6 7.1 Monadic Operators 6 7.2 Dyadic Operators 7 7.3 Other Operators 11 8. SUSPENDED FUNCTIONS 12 9. SYSTEM COMMANDS 13 9.1 )CLEAR [] 13 9.2 )CONTINUE 13 9.3 )DROP 13 9.4 )ERASE 13 9.5 )FNS 13 9.6 )LBLS 13 9.7 )LIB [] 13 9.8 )LOAD 14 9.9 )OFF 14 9.10 )REL 14 9.11 )RESET 14 9.12 )SAVE [] 14 9.13 )SI 14 9.14 )STAT 14 9.15 )SYS [] 14 9.16 )VARS 14 9.17 )WSID [] 14 MAPL USERS GUIDE Table of Contents Page 10. COMMENTS 15 11. KEYBOARD INTERRUPTS 15 12. ERROR MESSAGES 16 12.1 DEFN ERROR 16 12.2 DOMAIN ERROR 16 12.3 INDEX ERROR 16 12.4 LENGTH ERROR 16 12.5 SYNTAX ERROR 16 12.6 SYSTEM ERROR 16 12.7 VALUE ERROR 16 12.8 WS FULL 17 12.9 INTERRUPT 17 12.10 LIBRARY EMPTY 17 12.11 NOT WITH SI 17 12.12 NOT FOUND 17 12.13 INCORRECT COMMAND 17 12.14 WS NOT FOUND 17 13. APPENDIX 1 - Sample Definitions 18 14. APPENDIX 2 - Internal Data Storage Format 19 15. APPENDIX 3 - The OPSYS Function. 20 MAPL USERS GUIDE Page: 1 1. INTRODUCTION MAPL is an interactive computer language, based on the language APL, and is designed to allow the programmer to define a library of programs, which can be easily used as single operations within other programs. In order to provide keyboard symbols for the many special operators which are available, lower case characters are used in many cases as the special symbols. In order to make it simpler for the user, Lower case is converted to upper case, and upper case input is converted to lower case, allowing the special operators to be entered using the SHIFT key. 2. CALCULATOR MODE MAPL works by evaluating expressions, and producing results. When MAPL is not running a program, it is in CALCULATOR MODE, which allows you to type in expressions, and to see the results. When in calculator mode, MAPL will space in five spaces from the left margin, and wait for a line of input. If it is an expression, MAPL will evaluate it, and display the result. NOTE: MAPL does not display the result if it is assigned to a variable in the last (leftmost) operator of the expression. MAPL evaluates all expressions from right to left. For example, if you type 5*3+1 when MAPL is prompting in calculator mode, You will get the result 20. MAPL first adds 1 to 3, producing 4, and then multiplies that result by 5, giving 20. Precedence can be forced using brackets, for example, typing (5*3)+1 would give the answer 16. There are two types of values which may be entered in an expression, 16 bit integers, and characters. Integer values can be entered using the decimal digits (0-9), the underscore character is used to indicate negative numbers. Character values are entered using the single quote character, "'". The single quote character can be included in the character string by using two adjacent quotes in the entered string, EG: 'DAVE''S PLACE'. Character data is represented as a character array, with a length equal to the number of characters in the entered string. Integer values are represented as a numeric array, with a length equal to the number of elements entered (Separated by spaces). EG: 1 2 _3 4 5 3. OPERATORS Operators are indicated by special characters, either by the ASCII graphic characters,such as '+' or by LOWER CASE alpha characters. Operators are the basic built in functions, which enable the programmer to manipulate and store data. Operators may be MONADIC, requiring one argument value which is located immediatly to the right of the operator, or DYADIC, requiring two argument values, which are located both to the left and right of the operator symbol. MAPL USERS GUIDE Page: 2 When DYADIC (two operand) operations are performed on any values, the two sides must be the same length (number of elements). The operation is performed on each corresponding pair of elements from the two arrays. For example: 1 2 3 + 4 5 6 produces the result 5 7 9 (1+4, 2+5, 3+6). If the two values are not the same length, then one of the two values must be of length one (1). If this is the case, then its value is automaticaly extended to match the other operand value. For example: 2 + 4 5 6 is equivalent to 2 2 2 + 4 5 6, and yields the answer 6 7 8. 4. USER VARIABLES User variables are denoted by a name consisting of the characters from (@, A-Z), which may be up to 31 characters long. The value produced by an expression can be assigned to variable, using the '=' assignment operator. For example ABC = 4 5 6 + 1 2 3 would assign the result (5 7 9) to the variable ABC. When assigned a value in this manner, the variable assumes the type, size, and content of the expression to the right of the '=' operator. 5. SYSTEM VARIABLES System variables consist of a single character, and are denoted by a trailing DOLLAR SIGN character. EG: 'O$'. System variables are used in expressions exactly the same way as user variables are, but the data saved/read from the variable is not stored in memory as data, but is used to set/interrogate system parameters, or to interface to entities external to the function definition or the MAPL system. The following system variables are implemented, the variables flagged with '*' can only be read, and may not be assigned a value. B$ - Buffer size. This variable contains the amount of space which is reserved by MAPL when evaluating an expression. It is initially set to 1024 in a clear workspace. This is enough space to deal character strings of 1021 characters, or numeric arrays of 510 elements. If assigned a value, sets the work buffer size. The amount of space required for character data is 3 + the number of characters in the data. For integer data, it is 3 + twice the number of elements in the array. This system variable affects the allocation and release of work buffers as expressions are nested, and should not be set from anything but a simple highest level expression. C$ - Character string. This variable returns a character string which is 256 characters in length, and contains the characters with the byte value from 0 to 255. When assigned a value, it acts as a local dump, discarding the assigned value. F$ - Formatted terminal I/O. This variable waits for a line of input from the terminal, and returns it as a character string. No prompt is displayed. If it is assigned a value, the value is displayed on the terminal WITHOUT a line-feed carriage return at the end. * K$ - Key Input, Reads a single keystroke from the keyboard. MAPL USERS GUIDE Page: 3 L$ - Line Number. This variable returns the number of the line which is being interpreted in the function definition which is being executed. When assigned a value, causes a jump to the indicated line AFTER the current expression has completed. If the assigned line number is greater then the number of lines in the function, causes the function to terminate. If the assigned line number is zero, causes NO jump to be taken, even if L$ has been assigned previously in the expression. If the assigned value is zero in length, has no effect of the previous state of L$. O$ - Origin value. This variable contains the system origin value. The origin value is the value at which indexes start. It controls the starting element number for indexed array access, and also the output offsets for some system functions such as '?', and 'i'. It is normally set to one (1) in a clear workspace. * P$ - Parameter value. This variable returns the value of the argument value to the currently executing function definition. If the function was not given an argument, then P$ will return a zero length numeric array. * R$ - Remainder. This system variable will return the remainder which was generated in the last division operation. S$ - Seed. This variable reads/sets the random seed used by the ROLL ('?') operator. T$ - Terminal I/O. When this variable is read, MAPL prompts with a '?' at the terminal, and waits for an expression to be entered. The expression is then evaluated, and the result is returned. When T$ is assigned a value, the value is displayed on the terminal, followed by a line-feed, carriage return pair. * W$ - Returns the amount of memory which is free (unused) in the current workspace. MAPL USERS GUIDE Page: 4 6. USER DEFINED FUNCTIONS User functionss or programs are collections of expressions which are assigned a name. The function can be executed simply by refering to it's name within another expression. Function names names may consist of the characters from (@, A-Z), and may be up to 31 characters in length. When used within an expression, User functions behave like monadic operators, accepting one value, and returning one value, It is not required that a value be passed to a function, in which case it will receive a zero length numeric array as it's passed parameter. 6.1 EDITING FUNCTIONS User defined functions are created and edited with the '$' character. The user types '$' where name is the name of the function he wants to edit. If it does not exist, it is created, otherwise it is edited. When the function is edited, the editor prompts with '[]', where is the number of the first free (unused) line in the function. While editing a function, the following commands are available: - Replaces the text on the current line with , and advances to the next line. [] - Move to line . [$] - Move to and display line . [$] - Display all lines from to end of function. [$] - Display entire function. [I] - Insert lines ahead of line , Prompt changes to '(n)', enter a null line to leave insert mode. [D] - Delete line . $ - Close function definition. $$ - Close function definition and lock function, locked functions cannot be edited, or displayed. Editing line 0 can be used to change the name of the function, If this is done, the old copy of the function will remain, and can be removed via the ')ERASE' command. If line 0 is changed so as to give in invalid function name, a DEFN ERROR will occur when an attempt is made to exit the editor. In this case, the editor will not terminate, but will remain active, at line [0] allowing the function name to be changed. MAPL USERS GUIDE Page: 5 Lables can be given to function lines, and consist of a valid variable name, starting in column 1, and followed by a colon (':'). Lines containing labels are outdented one column when displayed by the editor. Lables are symbol table entries, and are LOCAL to a function, existing only while the function is actually executing. Variables can be made LOCAL to a function definition by including the names in the header line (line 0), separated from the function name by semicolons. When a function is invoked, any LOCAL variables will replace any external variables of the same name, for the duration of execution of the function. When the function exits, the local variables are destroyed, and the external variables are restored. When a user defined function is executed, the value of its parameter can be accessed via the system variable 'P$'. The value returned by the function will be the value of the last expression evaluated within the function. Expressions within functions which do not assign the result to a variable will be printed, the same way as in calculator mode. A useful trick, is to assign the final value to the system "DUMP" variable 'C$', to prevent it from being displayed before it is returned. MAPL USERS GUIDE Page: 6 7. MAPL OPERATORS 7.1 Monadic Operators The following operators require a single argument, and produce a single result. All arguments are placed to the immediate right of the operator symbol. Operator Operator Description of operator. Name Symbol ---------+---------+-------------------------------------------------------- Classify | c | Produces a single element value, which is a zero(0) if | | the argument value contained character information, or | | a one(1) if the argument value was numeric in content. ---------+---------+-------------------------------------------------------- Execute | e | Accepts only character arguments, and evaluates the | | argument string as an expression, returning the result. | | A zero length argument, causes no operation, and a zero | | length numeric array is returned. ---------+---------+-------------------------------------------------------- Index | i | Accepts only a numeric argument of length one(1), and Vector | | produces an assending array, starting with the value of | | the system origin variable 'O$',and containing a number | | of elements equal to the value of the argument. A value | | of zero as an argument will generate a numeric array of | | zero elements. ---------+---------+-------------------------------------------------------- Reverse | r | Produces an array of the same length as the argument, | | containing the same elements, but in the reverse order. ---------+---------+-------------------------------------------------------- Roll | ? | Produces an array of the same length as the argument, | | containing random numbers between the value of the 'O$' | | system origin variable, and the value contained in the | | corresponding element of the argument. ---------+---------+-------------------------------------------------------- String | s | Produces a character array, containing the character | | representation of the numeric argument. If more than | | one element is present in the argument, each element is | | converted to a character string and separated by one | | space in the output. A zero length numeric argument, | | Produces a zero length character result. ---------+---------+-------------------------------------------------------- Shape | p | Produces a single integer value which is the number of | | elements in the argument value. ---------+---------+-------------------------------------------------------- Sort | ^ | Produces an array of the same length as the argument, | | containing index values required to place the argument | | value in non-decending order. Ie: the first element of | | the result contains the position of the smallest | | element in the argument, and so forth. Each index value | | for each element in the argument will occur only once | | in the resultant index array. ---------+---------+-------------------------------------------------------- Branch | b | Causes a jump to the line number indicated by the | | operand value, AFTER this expression is executed. ---------+---------+-------------------------------------------------------- MAPL USERS GUIDE Page: 7 7.2 Dyadic Operators The following operators require two arguments, which occur both to the right and the left of the operator. In most cases, the arguments must be the same length, except for the case where one operator is of length one(1), and the other is not. In this case, the argument of length one is automatically expanded to the length of the the other argument, with each element of the new expanded array equal to the value of the origional element in the array. Operator Operator Description of operator. Name Symbol ---------+---------+-------------------------------------------------------- Add | + | Accepts only numeric arrays, producing an array of the | | same length as the arguments, containing the sum of the | | elements in the argument arrays. ---------+---------+-------------------------------------------------------- Subtract | - | Accepts only numeric arrays, producing an array of the | | same length as the arguments, containing the difference | | of the corresponding elements in the arguments. ---------+---------+-------------------------------------------------------- Multiply | x | Multiplys the corresponding elements of the argument | | arrays to produce a resultant array of the same length. | | Accepts numeric arrays only. ---------+---------+-------------------------------------------------------- Division | % | Divides the corresponding elements of the argument | | arrays, to produce a resultant array of the same length | | The remainder after the division of the first two | | elements is assigned to the system variable 'R$'. The | | divisor is the array FOLLOWING the operator. | | Accepts numeric arrays only. ---------+---------+-------------------------------------------------------- Modulus | m | Performs a division of the elements of the argument | | arrays, and produces an array of the same length, which | | contains the remainder after each division. The divisor | | is the array PRECEDING the operator. | | Accepts numeric arrays only. ---------+---------+------------------------------------------------------- Logical | & | Performs a bitwise logical AND of the argument values, And | | producing a result of the same length. ---------+---------+------------------------------------------------------- Logical | ! | Performs a bitwise logical OR of the argument values, Or | | producing a result of the same length. ---------+---------+------------------------------------------------------- Exclusive| | | Performs a bitwise exclusive or of the arguments, Or | | producing a result of the same length. ---------+---------+------------------------------------------------------- Greatest | g | Accepts numeric arguments only, produces an array of | | the same length as the arguments, containing the | | larger of each corresponding set of elements. ---------+---------+------------------------------------------------------- Least | l | Accepts numeric arguments only, produces an array of | | the same length as the arguments, containing the | | smaller of each corresponding set of elements. ---------+---------+------------------------------------------------------- MAPL USERS GUIDE Page: 8 Operator Operator Description of operator. Name Symbol ---------+---------+------------------------------------------------------- Equality | == | Produces an array of the same length as the arguments, | | containing one(1) or zero(0) values indicating if the | | corresponding elements of the arguments are equal. ---------+---------+------------------------------------------------------- Not Equal| -= | Produces an array of the same length as the arguments, | | containing one(1) or zero(0) values indicating if the | | corresponding elements of the arguments are NOT equal. ---------+---------+------------------------------------------------------- Greater | > | Accepts numeric arrays only, and produces a result of Than | | the same length as the arguments which contains one(1) | | or zero(0) values indicating if the corresponding | | elements of the preceeding arguments are greater than | | the corresponding elements of the following argument. ---------+---------+------------------------------------------------------- Less | < | Accepts numeric arrays only, and produces a result of Than | | the same length as the arguments which contains one(1) | | or zero(0) values indicating if the corresponding | | elements of the preceeding arguments are less than the | | corresponding elements of the following argument. ---------+---------+------------------------------------------------------- Greater | >= | Accepts numeric arrays only, and produces a result of Equals | | the same length as the arguments which contains one(1) | | or zero(0) values indicating if the corresponding | | elements of the preceeding arguments are greater than | | or equal to the corresponding element of the following | | argument. ---------+---------+------------------------------------------------------- Less | <= | Accepts numeric arrays only, and produces a result of Equals | | the same length as the arguments which contains one(1) | | or zero(0) values indicating if the corresponding | | elements of the preceeding arguments are less than or | | equal to the corresponding elements of the following | | argument. ---------+---------+------------------------------------------------------- Extract | / | The preceeding argument to this function must be of | | numeric content. The result produced will be of the | | same type as the following argument, and will consist | | all of the elements from the following argument which | | have a corresponding NON-ZERO value in the preceeding | | argument. The number of elements in the result will be | | equal to the number of non-zero elements in the first | | argument. If the preceeding argument is of length one, | | it will be expanded to the same length as the follow- | | ing argument, and will cause the result to be either | | the entire following argument, or a zero length array, | | depending on it's value. ---------+---------+------------------------------------------------------- MAPL USERS GUIDE Page: 9 Operator Operator Description of operator. Name Symbol ---------+---------+------------------------------------------------------- Join | ; | Produces a single result, consisting of all of the | | elements from the first argument, followed by all of | | elements from the second argument. The two arguments | | must be of the same type. ---------+---------+------------------------------------------------------- Take | t | The first argument to this operator must be a numeric | | value of length one(1). The result produced is an | | array of length , consisting of the first | | elements of the second argument,where is the value | | of the first argument. If is greater than the | | number of elements in the second argument, the result | | is padded with spaces for character values, and zero's | | for numeric values. ---------+---------+------------------------------------------------------- Drop | d | Similar to 'TAKE' above, but returns the remaining | | elements of the second argument, after the first | | elements have been removed. If equals or excedes | | the number of elements in the second argument, then a | | zero length array is returned. ---------+---------+------------------------------------------------------- Find | f | Returns the starting position (in the first argument) | | of the pattern specified by the second argument. If | | the pattern is not found, the number returned is one | | higher than the highest element index in the first | | argument. The index value returned is adjusted for the | | the current setting of the system origin variable. O$ ---------+---------+------------------------------------------------------- Translate| n | Returns an integer array, with the same length as the | | right-hand argument, which contains the index values | | into the left-hand argument for the corresponding | | elements from the right-hand argument. If an element | | from the right hand operand does not occur in the left | | hand argument, then the corresponding index value will | | be one greater than the highest valid index value for | | the left-hand argument. Due to the way translate looks | | through the left argument, it will always return the | | highest index value for elements which occur more than | | once in the left-hand argument. ---------+---------+------------------------------------------------------- Union | u | Returns an integer array, with the same length as the | | left hand argument, which contains either a zero or a | | one, indicating if the corresponding element from the | | left-hand argument is contained within the right-hand | | argument. ---------+---------+------------------------------------------------------- Assign | = | Assigns the value given as the right operand to the | | variable name given as the left operand. ---------+---------+------------------------------------------------------- MAPL USERS GUIDE Page: 10 Operator Operator Description of operator. Name Symbol ---------+---------+------------------------------------------------------- Opsys | o | This operator provides an interface to operating | | system functions. It's usage will vary from system to | | system, but the following general syntax rules apply: | | The left-hand operand is always a simple integer, of | | length=1, and indicates which operating system service | | is to be invoked. The right hand operand can be any | | value and any length, depending on the requirements of | | the selected operating system function. The value | | returned by the function may also be of any size and | | type. See the appendices for more information on OPSYS. ---------+---------+------------------------------------------------------- MAPL USERS GUIDE Page: 11 7.3 Other Operators The following operators do not fit into the class of monadic or dyadic operators, and are described here. Operator Operator Description of operator. Name Symbol ---------+---------+-------------------------------------------------------- Travel | \ | This operator takes another operator as it's left | | argument, which can be one of (+,x,&,!,|,g,l).The given | | operation is performed against each element of the | | numeric array given as the right argument. The result | | produced is of length one, and is equivalent to | | separating each element of the second argument with the | | specified operator. EG: +\1 2 3 is equivalent to 1+2+3, | | and would produce the result 6. If a zero length array | | is given as the second argument, the result is a number | | known as the IDENTITY value for that operation, and is | | the number which has no effect when used as an argument | | for that operation. Ie: The identity value for addition | | is ZERO, and when added to another value, produces the | | same value. ---------+---------+-------------------------------------------------------- Nest | ( and ) | Brackets, allow expressions to be nested and used as | | single values in another expression, thereby allowing | | normal right to left precedence to be altered. ---------+---------+-------------------------------------------------------- Index | [ and ] | Allow access to elements of an array, as determined by | | the expression inside the square braces. | | EG: (ri5)[1 3] produces the result 5 3 (if O$=1). | | ABC[1 3]=4 7 Assigns the value 4 to the first | | element of the variable ABC,and the | | value 7 to the third element. ---------+---------+-------------------------------------------------------- MAPL USERS GUIDE Page: 12 8. SUSPENDED FUNCTIONS If an error condition is encountered while executing a user defined function, the execution of that function will be terminated, and an error message printed, indicating the type of error encountered, the name of the function being executed, and the line number on which the error occured. In order to aid in debugging, the function will actually be SUSPENDED in execution, allowing access to it's symbols and local variables from calculator mode. When a function is suspended, buffer and stack space allocated to that function will not be released until a ')REL' or ')RESET' command is issued, which will terminate the function and release it's local symbols and buffer space. This is normally done after determining the cause of the error. The equivalent of a ')RESET' command will be performed whenever a function is edited, or any symbol is erased via the ')ERASE' command. The names of GLOBAL variables which were superceded by local variables in a suspended function will still be visible in the ')VARS' variable list, even though they will not be accessable until the suspension of the function containing local variables of the same name is cleared. Line labels belonging to suspended functions will exist in the symbol table, and can be seen with the ')LBLS' command. MAPL USERS GUIDE Page: 13 9. SYSTEM COMMANDS The following is a description of the system commands which may be entered while in calculator mode. System comamnds may not be used from within a user defined function. The parameters indicated by square braces are optional. 9.1 )CLEAR [] Clears the workspace, setting it's name to 'CLEAR WS', and initializes the symbol table, erasing all variables and functions. The system variables are reset to their default values. If the optional parameter is given, then that many bytes are reserved in the workspace for the symbol table. The default value for the symbol table size is 1000 bytes. Symbol table entries are required for function names, variable names, and for local variables and lables in executing functions. Each entry requires a number of bytes of memory equal to the number of characters in the symbol name plus four. Symbol names can be from 1 to 31 characters in length. 9.2 )CONTINUE Saves the currently loaded workspace on the disk, under the workspace name 'CONTINUE', and then terminates the session. If a workspace by the name of 'CONTINUE' exists when MAPL is first executed, It will be automaticaly loaded. 9.3 )DROP Removes the named saved workspace from the disk. 9.4 )ERASE Removes the named symbol (function or variable) from the workspace. 9.5 )FNS Displays the names of all user defined functions which are present in the currently loaded workspace. 9.6 )LBLS Displays the names of all user defined function labels which are currently in the symbol table. Function labels are only placed in the symbol table during execution of that function, and should not be visible unless the workspace contains suspended functions. 9.7 )LIB [] Displays the names of workspaces which are saved on the disk. If the operand is specified, it is used as a mask for the directory listing. I.E: If you enter ')LIB B*', all saved workspace names which start with a 'B' would be displayed. MAPL USERS GUIDE Page: 14 9.8 )LOAD Loads the named saved workspace from disk, and makes it the active workspace. When the workspace is loaded, if the symbol '@LX' is found in the new workspace, it is evaluated, and should return a string value which is then executed (via 'e'). 9.9 )OFF Terminates the session, returning to the operating system. 9.10 )REL Releases the most recently suspended function, reclaiming it's stack and buffer space, and removes any local variables it may have had. 9.11 )RESET Releases all suspended functions, reclaiming stack and buffer space, as well as removing all local variables from the symbol table. 9.12 )SAVE [] Saves the currently loaded workspace on the disk under the given name. If no name is specified, the workspace is saved under it's own name. 9.13 )SI Displays a list of all functions which are suspended in the workspace, including the line number on which suspension occured, and the names of all local variables belonging to the function. 9.14 )STAT Displays information about the currently loaded workspace, included in this display are symbol table size, number of symbols, amount of free space in symbol table, and the amount of free space in the workspace. 9.15 )SYS [] Executes the DOS command . If no command is supplied, enters the dos, allowing return to MAPL via the DOS 'RETURN' command. 9.16 )VARS Displays the names of all user variables which are present in the active workspace. 9.17 )WSID [] Displays the name of the current workspace. If is supplied, sets the workspace name. MAPL USERS GUIDE Page: 15 10. COMMENTS Any line which begins with an asterix ('*') is treated as a comment, and is ignored by the interpreter. 11. KEYBOARD INTERRUPTS The CONTROL-C character can be used to interrupt MAPL in several ways. 1) If a user defined function is executing, typing a CONTROL-C will interrupt the execution of that function, causing a suspension. 2) If a CONTROL-C is entered while editing a function, the editor will be aborted, and any changes which were made will be lost. 3) If a CONTROL-C is entered in response to a 'T$' of 'F$' prompt, the input request will be canceled, and any functions which were in a state of execution will be suspended. MAPL USERS GUIDE Page: 16 12. ERROR MESSAGES The following error message are produced by the interpreter. 12.1 DEFN ERROR Results from an attempt to edit a function name which is not editable, either because it is locked, is an invalid name, or that name is already in use for a variable. Also results when exiting a function after the name has been made invalid, or from errors during editing. 12.2 DOMAIN ERROR Results from an attempt to perform an operation on a value which is not in the domain of the function being used, such as an argument to a function which is the wrong type (character or numeric) for that function, or for the other argument in a dyadic function. This error also results from any error inside of a locked user defined function. 12.3 INDEX ERROR Results from an attempt to index a value with a index value which falls outside of the range of valid index values for the first value. 12.4 LENGTH ERROR Results from use of a value which is not of a length required for use by a particular function. Also results from use of a dyadic function on values which are of incompatable lengths. 12.5 SYNTAX ERROR Results from any statement which does not follow the syntax rules. 12.6 SYSTEM ERROR Results from an internal error condition, which can not be accounted for. A series of HEX values will be dumped out following the error, which contains valuable information about the current state of the system at the time the error was detected. Write the values down, and include them with a bug report if the problem persists. 12.7 VALUE ERROR Results from an attempt to use a symbol that has no value. Any reference to an undefined symbol other an an assignment will result in this error. MAPL USERS GUIDE Page: 17 12.8 WS FULL Results from any operation which requires more memory then is currently free a the time the operation was attempted. 12.9 INTERRUPT This message is displayed whenever an interrupt in execution is caused via a control-C character from the terminal. 12.10 LIBRARY EMPTY Results froma ')LIB' command, when there are no matching files on the disk. 12.11 NOT WITH SI Results from any command which can not be completed while there is a suspended function in the workspace. 12.12 NOT FOUND Results from an attempt to ')ERASE' a symbol which has not been defined. 12.13 INCORRECT COMMAND Results from a system command which is unrecognized, or has been given invalid operands. 12.14 WS NOT FOUND Results from an attempt to ')LOAD' or ')DROP' an non-existant workspace. MAPL USERS GUIDE Page: 18 13. APPENDIX 1 - Sample Definitions The following are some sample function defintions. $ROTATE [1] * ROTATES THE OPERAND VALUE ONE PLACE TO THE LEFT. [2] C$=1dP$;1tP$ [3] $ $ONEBLANK [1] * CONVERTS ALL MULTIPLE OCCURANCES OF BLANKS TO SINGLE BLANKS. [2] C$=(0==(P$==' ')&ROTATE' '==P$)/P$ [3] $ $PARSE;A [1] * STRIPS OFF THE FIRST WORD FROM THE GLOBAL VARIABLE 'CMD', REPEATED [2] * CALLS TO 'PARSE' WILL RETURN THE NEXT WORD. [3] CMD=(1+pA=(_1+CMDf' ')tCMD)dCMD [4] C$=A [5] $ $DEAL [1] * DEALS A DECK OF CARDS, SIZE DETERMINED BY PARAMETER. [2] C$=^?P$+P$t0 [3] $ $SIZE [1] * RETURNS THE AMOUNT OF MEMORY (BYTES) REQUIRED BY THE PARAMETER. [2] C$=3+(1+cP$)xpP$ [3] $ $CRLF;CMD;OUT [1] * PRODUCES A STRING, CONTAINING WORDS FROM THE PARAMETER, SEPARATED [2] * BY CARRIAGE RETURN/LINE-FEED PAIRS (NO SPACES). [3] OUT=0tCMD=ONEBLANK P$ [4] TOP: OUT=OUT;C$[14];C$[11];PARSE [5] b(pCMD)/TOP [6] C$=2dOUT [7] $ $CRSTRING;VAR [1] * THIS FUNCTION SEPARATES WORDS IN A STRING WITH CARRIAGE RETURNS. [2] VAR[(VAR==' ')/ipVAR=ONEBLANK P$]=C$[14] [3] C$=VAR [4] $ $HEX [1] * THIS FUNCTION CONVERTS A STRING HEX NUMBER INTO AN INTEGER VALUE. [2] C$=+\1 16 256 4096x4tr('0123456789ABCDEF'nP$)-O$ [3] $ MAPL USERS GUIDE Page: 19 14. APPENDIX 2 - Internal Data Storage Format When data is assigned to a variable, or simply used in an expression, it converted to a standard internal data structure. The format of this structure is as follows: [Type field] (1 Byte) [Length field] (2 bytes) [Data field] (Variable length) The type field consists of a single byte, and indicates the classification of the content of the structure. Currently the only values used for the type byte are 0 for character information, and 1 for integer information. The Length field contains a 16 bit number indicating how many elements are in the structure. The data field contains the actual data elements, stored in REVERSE order. For character data, the elements are one byte each, and for integer data, the elements are two bytes in size. MAPL USERS GUIDE Page: 20 15. APPENDIX 3 - The OPSYS Function. The OPSYS ('o') function provides an interface to specific operating system functions, which may vary depending on the operating system used. Care should be taken when writing definitions which use this operator, as they may not be transportable to other systems. The OPSYS function supplied with CUBIX has the following functions: Function Right Hand - Description Code Operator --------+------------+------------------------------------------------------ 0 | Character | Passes the operand string to the DOS, to be executed | | as a DOS command. Returns a standard DOS return code. --------+------------+------------------------------------------------------ 1 | Character | Opens the file indicated by the operand for a serial | | READ operation. Returns a file control block (FCB) | | which is an integer array of length 261 if successful | | or a standard dos return code (length 1) if failure. --------+------------+------------------------------------------------------ 2 | Character | Opens the file indicated by the operand for a serial | | WRITE operation. Returns a file control block (FCB) | | if successful, or a standard return code if failure. --------+------------+------------------------------------------------------ 3 | Character | Tests for existance of a file, returns standard DOS | | return code value. --------+------------+------------------------------------------------------ 4 | Integer | Reads data from main memory. A byte of memory is | | fetched at the address contained in each element of | | the operand. An integer array is returned. --------+------------+------------------------------------------------------ 5 | Integer | Writes data to main memory. The first element of the | | operand is taken as the address, and the value of all | | following elements are written sequentially as data. --------+------------+------------------------------------------------------ 6 | Integer | Executes a System Service Request (SSR). The five | | element operand has the following format: | | (SSR NUMBER), (A&B), (X), (Y), (U) | | After executing the system request, the following | | five element array is returned: | | (RETURN CODE), (A&B), (X), (Y), (U) --------+------------+------------------------------------------------------ FCB | Character | Writes the operand data to the file indicated by the | | supplied FCB variable. This function updates the FCB, | | and therefore it must be given as a simple variable, | | not contained in an expression or within brackets. --------+------------+------------------------------------------------------ FCB | 0 | Reads a line from the open file, and returns a char- | | acter string if successful, Integer return code if | | not. See above for restriction of FCB specification. --------+------------+------------------------------------------------------ FCB | 1 | Closes the file indicated by FCB. Returns standard | | DOS return code. See above for restriction of FCB. --------+------------+------------------------------------------------------ FCB | 2 | Rewinds the indicated file. Returns DOS return code. | | See above for restriction of FCB specification. --------+------------+------------------------------------------------------