@9Ox1P P A R A S O L L A N G U A G E M A N U A L Copyright (C) 1982 - 1986 by Para-Soft and Shay O. Walters All rights Reserved Placed in the Public Domain October, 1986 by Shay O. Walters PARASOL is a language I developed myself for my own business use. It has been tailored to provide the features I needed for the applications I have developed over the last several years. Due to the overwhelming popularity of the MS-DOS systems running on the 8086, I feel that there is no longer any need to keep this to myself. Therefore, I am placing this into the public domain so that others may benefit from it. There used to be a more complete manual, but a system crash before it was backed up destroyed that effort. I have spent what time I could to polish this older version of the documentation to the point that it could be really useful. If you have specific questions, I'll be glad to help if I can. I can be contacted on Compuserve at [73247,1163] or on GENIE at [SHAY]. (You are more likely to get a timely responce on GENIE...Compuserve is TOO expensive). Also, I can be reached (as of 10/86) at 803-799-0180 by phone. I am uploading a library of source code to a video- tape rental store management system which should give many examples of business-type usage of the language. I may be uploading other source at a later date. All the usual disclaimers apply. I have used this for several years, and for the last couple of years, I have found only one or two bugs, and I use it quite a lot, and I compile some VERY large programs (18,000 lines or so). BUT, I generally stick with a known layout and follow that pattern in other modules. Other programmers may possibly do things in a way which doesn't work, so I can't guarantee that it will be bug-free for you, but I would like to be informed of anything you feel IS a bug. Being public domain, this is absolutely free for anyone to use for personal use. For any profit-making usage of this compiler or its source-code, a $25.00 registration fee is required. Make your check payable to: Shay Walters / Para-Soft Phone: 803-799-0180 P.O. Box 6273 GE-MAIL: SHAY Columbia, S.C. 29260 CompuServe: 73247,1163 Registered users will be informed of availability of other software written in PARASOL and will generally get better support for problems or questions. The only additional restriction I will impose is that if anyone uses this source code as a basis for writing a compiler for another type of computer or operating system (say 8086 or 68000, for example) that I receive a copy of that source, too. It will not be disclosed to others, if that is what you wish. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:1 The library of the source code for the compiler contains the following files: PASM.SUB A SUBMIT file to assemble the compiler LBASE.ASM The global memory definitions. LCOMMON.ASM The global subroutines. LMISC.ASM Miscellaneous support functions. LSTMT.ASM The statement-compilation routines. LEOJ1.ASM The final forward-reference fixup. LEOJ2.ASM The support library for the compiled code. NOTE: I have used a modified version of LOAD which forces all undeclared data areas to binary zeros. The standard CP/M LOAD program will fill any undeclared data with garbage. I suggest that you use DDT instead of LOAD to make the COM files (fill memory with zeros before reading in the HEX file). It "should" work with LOAD, but I can't guarantee it. I no longer even have an unmodified copy of LOAD to try it with, it caused me no end of problems, so I destroyed all copies of it many years ago and use only the version I modified. Since that's part of DRI's licensed programs, I can't release it with this package. Also, the source, as supplied is not quite compatible with DRI's ASM assembler. It will do better with MAC or RMAC. I have a specially modified version of ASM, as well. If you want to try using ASM, you will need to eliminate all multi-statement lines: Anywhere an exclamation mark ("!") appears, (except inside string literals), it should be replaced with CR/LF. DRI's ASM is doc- umented as supporting the "!" as a multi-statement separator, but it doesn't work following DB or DW pseudo-ops. Also, there are several special characters such as underscore, AT-sign (@), and period which may or may not be acceptable to the various DRI assemblers as part of a variable name. The source code is really being supplied for those of you who are just curious about how the insides of a compiler (at least, this compiler) work. If you have some special feature you would like to have in the language, let me know about it, and maybe I can install the feature for you. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:2 LANGUAGE DESCRIPTION LANGUAGE DESCRIPTION PARASOL is not modeled after any one particular language, but has features derived from COBOL, ALGOL, and PASCAL (and maybe just a touch of BASIC). The individual statements are COBOL-like while the structure of the language more closely follows ALGOL. The language provides many high-level constructs, especially in the area of file record I/O, yet it maintains the closeness to the machine hardware which is so necessary in those difficult situations. PARASOL is a single-pass compiler. The object code (.COM only, no REL capability) is produced as the source code is read, and the source code is read only once. Forward references are resolved in the object file at whatever points the compiler detects there resolution in the source code. There is a final fix-up pass folling the end of the source file which connects all forward references to the built-in support routines. PARASOL was designed to be a highly-efficient language for the Z80 and 8080 microprocessors. Most PARASOL statements require either several machine-level instructions, or a subroutine-call. However, only the subroutines needed by a program are included with the object-code for that program, there is not a large subroutine library overhead as most high-level languages require. A variety of compiler switches are supported which provide features ranging from compiler-listing format and disposition to run-time protection features. The philosophy behind PARASOL is to provide the most efficient object code possible, while retaining the readability which makes program debugging and maintenance simpler. PARASOL was designed to be straightforward, easy-to-read, and self- documenting. It was not designed to provide the maximum processing power with the least coding effort. Although PARASOL is actually a "medium-to-high-level" language (as opposed to a high-level language), it provides many advanced constructs which are not found together in any other single language. PARASOL is ideally suited for applications ranging from process-control to business-accounting packages. For process-control, and other "real-time" applications, PARASOL offers the advantages of very fast execution time, and compact object-code size which minimizes the amount of ROM which must be included in a controller. For business and accounting applications, PARASOL supports a BCD numeric format which eliminates "round-off" or "truncation" errors inherent in the binary floating-point formats used by many other languages. Also, due to the compact object-code produced, an application module may contain more application functions than many other compilers will allow due to object-code size limitations. This allows fewer overlays and/or program "chain"'s; and even when one module must execute another module, the program-loading time is reduced due to the smaller object- code size. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:3 LANGUAGE DESCRIPTION LANGUAGE DESCRIPTION PARASOL also provides the capability of compiling a program which is larger than the available memory through the use of overlays. See the SEGMENTED statement for further information about this. PARASOL is generally not suited to scientific or mathematical applications, because there is no floating-point capability, nor built-in provision for handling multi-dimensional arrays. The language syntax of PARASOL combines the readability of COBOL with the structure of ALGOL, PASCAL, etc. All statements start with what would be called a VERB in COBOL, but anywhere that a single source-statement may appear, a list of statements bounded by BEGIN and END may appear. Identifier-scope rules BEGIN END parallel those of ALGOL, where an identifier is global throughout the block in which it is declared, and undefined outside that block. Strictly speaking, there are no reserved-words in PARASOL, only key-words. Key-words are 'reserved' in context only. Any key-word may be used as a variable-name or statement-label if desired, although this is discouraged, since, when a syntax-error is encountered by the compiler, it begins compiling again with the next key-word it finds following the error. For example: ADD SUBTRACT TO MULTIPLY GIVING DIVIDE ___ ______ ADD TO GIVING ___ ______ will compile code which will add two values named "SUBTRACT" and "MULTIPLY" and store the result in a variable named "DIVIDE". A problem may arise, however, if the word GIVING is misspelled. GIVING The compiler will print an error for the unrecognised word, then will attempt to compile a DIVIDE statement. For further DIVIDE information see the section on valid identifier-names which follows. There is also a compiler option (LIMIT WORD) which makes all key-words into reserved-words. This prevents any accidental usage of key-words as identifiers, and also speeds the compilation process for very large programs. ARRAYs are not currently implemented in PARASOL. This was a design consideration, but since generalized array-processing could not be made as efficient as user-programmed POINTER usage, POINTER and since the inclusion of arrays in the language would have complicated the construction of the compiler enormously, I decided to go with POINTER capability only. I have found that POINTER although there is a certain amount of discomfort getting accustomed to working without arrays, that the usage of POINTERs POINTER has all the capabilities of arrays and many fewer disadvantages than one would expect. Also the usage of POINTERs is inherently POINTER more flexible than arrays, since the memory past the end of a program which would generally be wasted, can be used for storage of data, also a subscript generally must be re-evaluated, and a new index computed each time a subscript is used, but a POINTER POINTER PARASOL language manual Copyright (C) 1982, Para-Soft Pg:4 LANGUAGE DESCRIPTION LANGUAGE DESCRIPTION can be set once and used many times with no additional overhead. The usage of the INDEX statement greatly simplifies the implementation of arrays. There is no provision in the compiler for linking-in relocatable assembler routines, but it is easy to perform this function using DDT or a similar program. Also there is rarely any need to resort to assembly-language coded routines, since all assembler capabilities are provided in PARASOL, and since the generated object code is nearly as efficient as assembly-language coding. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:5 RUNNING PARASOL RUNNING PARASOL PARASOL consists of two object modules: 1. PARASOL.COM 2. PARASOL2.OVL Both of these files must be available on the disk for correct operation. PARASOL2.OVL contains the code for the final forward-reference cleanup after the source has been processed, as well as the built-in procedure library. If PARASOL cannot locate PARASOL2.OVL on the current drive/user, it will also attempt to load it from drive A:, user 0. Start PARASOL with the following command: 12B>PARASOL [] PARASOL [ ] The source-name identifies the source file with a required extension of .SRC. If source-name has an extension, it will be used for the object file. The option-list is optional, but, if present, must be enclosed in square brackets. For example: 12B>PARASOL BUILD.CPM [PRINT CON] This will compile the source in BUILD.SRC and generate an object file as BUILD.CPM. The compiler listing will be displayed on the console. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:6 Compiler Switches Compiler Switches There are several compile-time switches which may be used to control various aspects of the compiler. These must appear in one of two places; either on the CP/M command line following the name of the program to compile, or as the first source line of the program. There is one extension to this rule: the first source line of the program may be a COPY statement which copies a COPY one-line library containing the compiler switches. Note that the compiler switches may appear BOTH on the CP/M command line in addition to the first source line for the same program. The switches on the command line are processed first, and some switches may only appear on the command line, and are invalid if specified in the source-code. The format of the compiler switches is: [ switch [ switch ] ... ] _ _ [ ] _ _ Note that the beginning and ending square brackets are boldface and underlined, indicating that they are required. The "switch" is any of the options from the table below. ADDRESS This option tells the compiler to list the address ADDRESS of the generated code on the compiler listing. CSTACK SIZE n This option specifies the size of the compiler's CSTACK SIZE n stack. The work SIZE is optional. "n" is the SIZE number of bytes to use for the compiler's stack space. The default value is 256 bytes. It is possible that a very deeply nested program may exceed the compiler stack/symbol-table space. This option is provided to circumvent that possibility. EXECUTE This option specifies that the compiler should EXECUTE execute this program immediately after compiling it. The program will not be executed if there were any compile errors. INPUT x This option must appear on the CP/M command line. INPUT This allows you to specify that the source file resides on drive "x". When this option is not used, the source file is assummed to reside on the current default drive. LIMIT STRING This option provides some small measure of LIMIT STRING protection against STRING variables overrunning STRING their allocated space. It causes all MOVEs of one MOVE string to another to be a fixed number of bytes. The number of bytes moved will be the smaller of the declared lengths of the two strings. LIMIT WORD This option causes all PARASOL key-words to be LIMIT WORD treated as reserved-words. A by-product of this is, since the compiler can skip the symbol-table search for any key-words, the compile time is PARASOL language manual Copyright (C) 1982, Para-Soft Pg:7 Compiler Switches Compiler Switches reduced somewhat. LEVEL This option tells the compiler to print the LEVEL syntactic-level counter beside each source line in the compiler-listing file. MAP This option specifies that the compiler should MAP list a map of the addresses of the built-in routines added to the end of the program. This map will be included at the end of the compiler listing file. MATCH This option tells the compiler to match-up BEGIN- MATCH BEGIN END pairs, as well as block markers of all other END types ( RECORD ENDREC, etc. ). On the compiler RECORD ENDREC listing, whenever the ending block marker is found, the line-number of the corresponding beginning marker is listed. MPM This option specifies that the generated object- MPM code MAY be run under MP/M, and that the PARASOL MP/M-interface routine should be included in the object-code. See the section about running under MP/M later in this manual. NOWARN This option inhibits compiler warning messages, NOWARN inhibits SEGMENT summary messages, and shortens SEGMENT the compiler summary at the end of the compile. NSTAR This option specifies that the generated object- NSTAR code will be run in multi-user mode under the n/Star operating system of Molecular Computers. This switch allows the compiler to handle various run-time error conditions correctly. See the section about running under n/Star later in this manual. If NSTAR is specified, MPM is assummed. NSTAR MPM NUMBER This option tells the compiler to print line- NUMBER numbers on the compiler listing. PRINT [CON] [PRN] [DISK x .ext] [FULL] PRINT CON PRN DISK FULL This option tells the compiler the disposition of the compiler-listing. The word PRINT may be PRINT followed by any of the above options in any order. CON - print the listing to the console. CON PRN - print the listing to the printer PRN DISK x .ext - print the listing to a disk file on drive DISK "x". The filename will be the same as the source filename with an extension of ".PRN" unless ".ext" is specified. FULL - Print the full listing, even if PRINT OFF FULL PRINT OFF appears within the source. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:8 Compiler Switches Compiler Switches STACK NONE This option specifies that the object program STACK NONE should NOT have a stack allocated. The program will use the small stack provided by CP/M. It is essential that this option be used only by programs which have little or no stack usage, since the stack space available by CP/M is quite limited. The STACK SAVE option is generally STACK SAVE preferred. STACK SAVE This option must appear on the CP/M command-line. STACK SAVE This option will allow a program to return to CP/M without rebooting. The CP/M stack is saved, but the PARASOL program has it's own stack. When the program finishes running, the CP/M stack is restored, and the program RETurns to CP/M. This option must not be used in any program which uses the HIMEM construct for data-storage, since that HIMEM is likely to wipe-out the transient CP/M module which is needed for this RETurn. STACK num This option allocates a fixed stack of "num" STACK num number of bytes immediately following the object module. *NOTE* Note that if neither STACK NONE or STACK num is *NOTE* STACK NONE STACK num specified, that the object program's stack will begin just below the BDOS, and grow downwards from there. This provides the maximum allowable stack space. STANDALONE This option specifies that the generated object- STANDALONE code will not be run under CP/M, or any "CP/M- compatible" operating system. Any statements which would cause a CP/M function call to be generated will be flagged with an error message. TAB n This option tells the compiler at what interval to TAB n expand TAB characters. The default is every 4 spaces. Note that the CP/M default with ED, and BDOS is every 8 spaces. "n" can be 2, 4, or 8 only. TABLE This option specifies that all PARASOL generated TABLE built-in routines should be accessed through a table in the low memory of the program. If this is NOT specified, all references to the built-in subroutines will be direct. The disadvantage to this is that the compiler must maintain a forward- reference marker for each call to each built-in subroutine, until it has been determined at which address these routines will be loaded. This greatly increases the symbol-table size, and consequently slows down the compiler, since it's symbol-table searches take longer. Also, a larger PARASOL language manual Copyright (C) 1982, Para-Soft Pg:9 Compiler Switches Compiler Switches program may be compiled with TABLE specified than TABLE without it, since a larger symbol-table may be handled. When TABLE is specified, the compiler inserts TABLE a jump-table at a known address in low-memory, and all references to built-in routines go through this jump table. When the built-in routines are actually loaded into the object code, this table is the only thing which needs to be patched to reflect those addresses. Z80 This option specifies that the generated object- Z80 code will be run on a Z80 processor, and that the compiler should take advantage of the special Z80 instruction set. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:10 EXPLANATION OF SYNTAX FORMAT USED IN THIS MANUAL EXPLANATION OF SYNTAX FORMAT USED IN THIS MANUAL Key-words are printed BOLDFACE, and where they are required, BOLDFACE they are also underlined. This means that a word which is __________ underlined __________ printed boldface but not underlined may be omitted from the source statement with no effect on the operation of that statement. When a clause (group of words) is optional, and may be omitted, the entire clause is enclosed in brackets. For example: ADD n1 TO n2 [ GIVING n3 ] ___ ______ ADD TO GIVING ___ ______ The word TO is optional and may be omitted with no effect on TO the operation of the statement. The GIVING clause is optional and may be omitted, but if ______ GIVING ______ used, the word GIVING is required. ______ GIVING ______ Generic items (items which describe the actual word to be placed in the position shown) are printed lower-case. When there is a choise of words, either key-words or generic words, they are printed inside braces ('{}'), and any which are not defaults are underlined. This means that if a choise is shown, and one entry is NOT underlined, that it is assumed if it is omitted. As a further explanation, refer to the following example: { RIGHT } RIGHT { LEFT } ____ LEFT ____ In this example, there is a choise of LEFT or RIGHT. Since LEFT RIGHT RIGHT is not underlined, it is optional, and will be assumed if RIGHT neither is specified, but LEFT is required if it is the option LEFT desired. Also LEFT and RIGHT can be seen to be key-words since LEFT RIGHT they are printed boldface. When a clause may be repeated, the clause is followed by an elipsis ('...'). For example: BYTE [id1] [VALUE value] ____ _____ BYTE VALUE ____ _____ [, [id2] [VALUE value] ]... _ _____ , VALUE _ _____ This indicates that the declaration of a second variable may be done in the same statement by following the first declaration with a comma and another declaration; likewise a third, fourth, etc. may follow. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:11 IDENTIFIERS, NAMES, LABELS, AND KEY-WORDS IDENTIFIERS, NAMES, LABELS, AND KEY-WORDS All identifers in PARASOL are composed of the following character-set: The upper-case alphabet A...Z The lower-case alphabet a...z The numbers 0...9 The special symbols: . (period) _ (underscore) ` (grave accent)* * note that the grave accent (`) is NOT an apostrophe (') All identifiers must begin with any character of the above set EXCEPT for a number. Any character after the first may be a number, if desired. Case (whether a letter is capialized or not) is NOT significant for key-words. The word MOVE may be placed in the source as 'MOVE', 'move', or even as 'MoVe'. NOTE that case IS significant for all labels and variable- names, for example, the following items are all considered to be separate identifiers by the compiler: ABC abc Abc aBc a.bc ab.c ab_c A_BC As an aid in choosing identifiers which do not conflict with any key-words it is convenient to use the period, underscore, and/or grave-accent in all identifiers. None of the key-words contain any special characters or numbers, so any identifier containing one of these characters is certain to be recognised as not being a key-word by the compiler. Identifiers may be any length up to 79 characters. 79 PARASOL language manual Copyright (C) 1982, Para-Soft Pg:12 VARIABLE-TYPES SUPPORTED BY PARASOL VARIABLE-TYPES SUPPORTED BY PARASOL PARASOL supports the following variable types: BYTE BYTE WORD WORD STRING STRING BCD BCD FIELD FIELD BIT BIT RECORD RECORD BYTE-POINTER BYTE-POINTER WORD-POINTER WORD-POINTER STRING-POINTER STRING-POINTER BCD-POINTER BCD-POINTER A BYTE variable is numeric and can have values from 0 to BYTE 255. Also, it may contain a single-character value. A WORD variable is numeric and can have values from 0 to WORD 65535. Also, it may contain a single- or double-character value. If it contains a single-character value, the hi-order byte is a null character (hex code ^h00). If it contains a double- character value, the second character is the high-order byte. All of the POINTER variables are treated as WORD variables unless POINTER WORD preceded by '@'. @ A STRING variable is alphanumeric, and may contain any STRING character except for the null character, since this character is used by the compiler to mark the end of the string. The length of a string is limited only by the size allocated. A BCD variable is numeric and may contain any decimal value BCD from -99999999999999 to +99999999999999 (up to 14 digits). BCD BCD variables are not compatible with binary variables (BYTE and BYTE WORD), and the CONVERT statement must be used to convert one type WORD CONVERT to another before they can be used together in an arithmetic operation. Compilers which handle more than 14 digits are available on request (up to 126 digits), but it should be noted that ALL BCD variables are fixed-length, and each additional two BCD digits require one additional byte of storage per variable. A BIT variable is boolean (logical) and can have only the BIT values TRUE (or 1) or FALSE (or 0). BIT's are allocated 8 bits TRUE FALSE BIT per byte (if declared contiguously), and actually occupy only one bit of storage. A FIELD variable is a fixed-length string. It is NOT FIELD interchangable with STRING variables in statements requiring STRING STRING variables. It is primarily designed for use in disk STRING records, and print-line formatting routines. It IS allowed to be used in a MOVE statement to or from a STRING variable, and in MOVE STRING conditional expressions with STRING variables. STRING POINTER variables are all special cases of WORD variables. POINTER WORD Any POINTER variable is treated exactly like a WORD variable when POINTER WORD referenced alone, however, when the POINTER variable is preceded POINTER by '@' ('AT' sign), the pointer is treated as what it points to. @ A BYTE POINTER is treated as a BYTE variable, a WORD POINTER is BYTE POINTER BYTE WORD POINTER treated as a WORD variable, etc. In all cases, the values which WORD are referenced by the POINTER are the values starting in memory POINTER at the location whose address is in the POINTER variable. Note POINTER that since a STRING POINTER does not have a length declared, it STRING POINTER PARASOL language manual Copyright (C) 1982, Para-Soft Pg:13 VARIABLE-TYPES SUPPORTED BY PARASOL VARIABLE-TYPES SUPPORTED BY PARASOL is treated as a STRING with "indefinite" length unless there is STRING some other limitation provided (as with the MOVE statement). MOVE A RECORD variable is a collective reference to a structure RECORD of variables, which may contain other RECORD variables. A RECORD RECORD RECORD variable is referenced only in MOVE, ACCEPT, and FILE statements, MOVE ACCEPT FILE and implicitly referenced in READ and WRITE statements. The READ WRITE length of a RECORD is the sum of the lengths of all subordinate RECORD fields. Note that since FIELDs and RECORDs have a length associated FIELD RECORD with them, there are no POINTERs for these types, since POINTERs POINTER POINTER do not have an associated length. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:14 NUMERIC QUANTITIES IN PARASOL NUMERIC QUANTITIES IN PARASOL The following varaible-types are considered to be binary- numeric by the compiler: BYTE, WORD, BYTE-POINTER, WORD-POINTER, BYTE, WORD, BYTE-POINTER, WORD-POINTER, STRING-POINTER, BCD-POINTER, @BYTE-POINTER, STRING-POINTER, BCD-POINTER, @BYTE-POINTER, @WORD-POINTER @WORD-POINTER also the following are numeric, but are listed separately, since they are incompatible with the binary-numeric types listed above: BCD, @BCD-POINTER BCD, @BCD-POINTER NUMERIC CONSTANTS NUMERIC CONSTANTS Numeric constants may be expressed in a variety of ways: (1): A character-string of length 1 or 2 (the first character is the low-order byte). (2): An identifier preceded by '#', example: # #x is a constant whose value is the 16-bit word which is the address of 'x'. (3): An identifier preceded by '##', example ## ##x is a constant whose value is the 16-bit word which is the length (in bytes) of the identifier 'x'. '##' may precede any variable type, the resulting value is determined according to the following table: a statement-label 0 a BIT variable 0 BIT a BYTE variable 1 BYTE a WORD variable 2 WORD a BCD variable 8 (assuming 14-digit BCD) BCD a STRING variable the defined maximum length STRING a FIELD variable the defined length FIELD a RECORD variable the defined length RECORD (4): An integer expression which is of the form: [^] ^ where is H,D,O,Q,B,h,d,o,q, or b. These represent: H,h - Hexadecimal (base 16) D,d - Decimal (base 10) O,o,Q,q - Octal (base 8) B,b - Binary (base 2) If the base is ommitted, decimal is assumed. Some examples are: ^h0d - 13 decimal - carriage return character ^q15 - 13 decimal ^b1011 - 11 decimal 15 - 15 decimal PARASOL language manual Copyright (C) 1982, Para-Soft Pg:15 NUMERIC QUANTITIES IN PARASOL NUMERIC QUANTITIES IN PARASOL (5): An expression of the form ( cnst operator cnst ) ( ) Note that this is the ONLY usage in PARASOL for parentheses. Each "cnst" in this example may be derived from any of the rules for constants, including this rule. The operator may be any of the following: operator Resulting value -------- --------------------------------- + The sum of the two values + - The result of subtracting the 2nd value from the 1st - * The product of the two values * / The quotient resulting from dividing the 1st value / by the 2nd value MOD The remainder resulting from dividing the 1st value MOD by the 2nd value AND The logical AND of the 16-bit bit-patterns formed AND by the two values OR The logical OR of the 16-bit bit-patterns formed OR by the two values XOR The logical exclusive-OR of the 16-bit bit-patterns XOR formed by the two operands. MAX The value of the larger of the two values MAX MIN The value of the smaller of the two values MIN (6): An identifier defined in a SET statement to equal a SET constant. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:16 STRING QUANTITIES STRING QUANTITIES STRING VARIABLES STRING VARIABLES The following variable-types are treated as strings of characters. STRING STRING @STRING-POINTER @STRING-POINTER FIELD FIELD Note that a FIELD variable is incompatible with STRING type FIELD STRING except in the MOVE statement and comparisons. MOVE STRING CONSTANTS STRING CONSTANTS A string constant may be declared using either quotes or apostrophes to delimit the characters. For example: 'This is a string delimited by "apostrophes"' 'This is a string delimited by "apostrophes"' "This string's delimiters are quotes" "This string's delimiters are quotes" Note that a string constant is ended only by the same delimiter which starts it. A compiler limitation prevents a string from crossing over a source line, so any string not terminated by the proper delimiter will be terminated at the end of the line. An error message will also be generated. Hex values for non-displayable characters may be directly coded into strings delimited by ~ (tilde). For example: ~ "~1b~=11" This is an example of a string which would cause the cursor to be positioned to the top-left corner of some types of CRT display device. This construct is very useful for this type of usage (CRT control characters, printer option controls, etc.) PARASOL language manual Copyright (C) 1982, Para-Soft Pg:17 CONDITIONAL EXPRESSIONS AND COMPARISONS CONDITIONAL EXPRESSIONS AND COMPARISONS Conditional expressions are used in the IF, WHILE, and UNTIL IF WHILE UNTIL constructs. These statements will accept any of the following formats: (1): numeric-value logocal-op numeric-value (2): numeric-value relational-op numeric-value (3): numeric-value (4): string-value relational-op string-value (5): string-value (6): bit-value (7): constant (including TRUE and FALSE) TRUE FALSE (8): relational-op A numeric-value may be any numeric variable or a numeric constant. A string-value may be any string variable or a string constant. Note that STRING and FIELD ARE compatible with this STRING FIELD construct. A logical-op may be AND, OR, or XOR. These are evaluated by AND OR XOR performing the associated boolean operation, and the condition is TRUE if the result of the boolean operation is NON-ZERO. The condition is FALSE if the result is ZERO. Numeric-values, constants, and BIT-values are true if non- BIT zero, and false if zero. If numeric-values or constants are used, the expression is evaluated at compile-time. A single JMP machine instruction will be generated, if needed. If it is not needed, no code will be generated. String-values alone are true if non-null, and false if null. Field-values alone are true if non-blank, and false if blank. Relational-op may be >,>=,=,<>,<=, or <. These follow the > >= = <> <= < 'classical' definitions of the symbols where: > is true if the value to the left is > larger than the value to the right. >= is true if the value to the left is >= larger or the same as the value to the right. = is true if both values are the same. = <> is true if both values are not the same. <> <= is true if the left-value is less than <= or the same as the right-value. < is true if the left-value is less than < the right-value. In option (8), where only a relational-op is shown, the condition is evaluated according to the microprocessor condition- codes as follows: < is true if CARRY is true. <= is true if CARRY is true or ZERO is true __ = is true if ZERO is true <> is true if ZERO is false. >= is true if CARRY is false. > is true if CARRY is false and ZERO is false. ___ NOTE: this construct is designed to be used ONLY following an MCALL statement. The microprocessor condition-codes are PARASOL language manual Copyright (C) 1982, Para-Soft Pg:18 CONDITIONAL EXPRESSIONS AND COMPARISONS CONDITIONAL EXPRESSIONS AND COMPARISONS undefined following all other PARASOL statements, and the effect of any given statement on the condition-codes may very well change between different versions of PARASOL if more efficient methods of implementing that statement become known to me. STRINGs are compared from left to right on a byte-by-byte STRING basis. The comparison is terminated on the first byte-pair which is not equal, or when both bytes compared are null. This means that for two STRINGs to compare equal, they must be the same STRING length, since the null-terminator in the shorter string will compare less than any other character in the longer string if the lengths are unequal. FIELDs are compared as though the shorter FIELD had been FIELD FIELD extended with blank characters to be the same length as the longer FIELD. Then both FIELDs are compared on a byte-by-byte FIELD FIELD basis until either an un-equal condition is encountered, or until all characters have been compared. When a STRING is compared with a FIELD, the comparison is STRING FIELD done as if the STRING were MOVEd to a FIELD of the same length, STRING MOVE FIELD then the comparison procedes the same as FIELD-to-FIELD FIELD FIELD comparison. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:19 LOCAL REDEFINITIONS ('OVERRIDES') LOCAL REDEFINITIONS ('OVERRIDES') In general, anywhere a variable-name is allowed, it may be followed by an override. An overridden variable-name has the following format: [@] variable-name [ override-list ]... _ _ @ [ ] _ _ (Note that the brackets above are underlined and boldface,indicating that they are required by the language syntax, and not present only for the description.) The override-list contains one or more of the following override-items, optionally separated by commas: + constant The constant is added to the address of the + variable-name. This is most useful with STRING, FIELD, and RECORD variables. Care STRING FIELD RECORD should be exercised when using this with STRING variables, since there is no protec- STRING tion provided to prevent accessing past the dynamic length of a string, and getting garbage left over from previous contents of the string. NOTE that when using this ____ NOTE ____ override with POINTER variables, that the POINTER address of the pointer is modified, not the address of what the pointer references. To change the address of what the pointer references, use the ADD statement. ADD - constant Same as above, but the constant is subtracted - from the address of the variable-name. BIT [:] constant The variable is treated as a BIT variable BIT : BIT with the bit position(s) specified by the constant. (Usually a hex constant). The variable-name MUST NOT be preceded by @. Note that several bits in one @ byte may be referenced at once by using a constant which has more than one bit in its binary form. BP The variable is treated as a 16-bit byte-pointer. BP The variable-name MUST be preceded by @. @ BYTE The variable is treated as an 8-bit BYTE variable. BYTE BYTE The variable-name MUST NOT be preceded by @. @ FIELD The variable is treated as a FIELD variable. FIELD FIELD The name MUST NOT be preceded by @. @ If the variable was originally a STRING, RECORD, STRING RECORD or FIELD, the length of the original variable is FIELD used if not overriden, otherwise, the LENGTH LENGTH override should be used to provide a length. The variable-name MUST NOT be preceded by @. @ LENGTH This may be used to specify a length to be used, LENGTH PARASOL language manual Copyright (C) 1982, Para-Soft Pg:20 LOCAL REDEFINITIONS ('OVERRIDES') LOCAL REDEFINITIONS ('OVERRIDES') or to provide a length for overriding variables which do not have a length with a type which requires a length. This override is meaningful only when the resulting variable-type is either FIELD, STRING, or RECORD. The variable-name FIELD STRING RECORD MUST NOT be preceded by @. @ RECORD The variable is treated as a RECORD variable. RECORD RECORD If the original variable was FIELD, STRING, or FIELD STRING RECORD, the declared size will be used if not RECORD overridden, otherwise, a LENGTH override must be LENGTH provided. The variable-name MUST NOT be preceded by @. @ SP The variable is teated as a 16-bit string-pointer SP and MUST be preceded by @. @ STRING The variable is treated as a STRING variable, and STRING STRING MUST NOT be preceded by @. @ WORD The variable is treated as a 16-bit WORD variable WORD WORD and MUST NOT be preceded by @. @ WP The variable is treated as a 16-bit word-pointer, WP and MUST be preceded by @. @ If multiple offset overrides are used (+ constant, - + - constant), the resultant address is modified by the algebraic sum of all offsets used. If multiple type-overrides are used, the last one specified is the one used. If multiple LENGTH overrides are used, the last one LENGTH specified is used. Note that the LENGTH override, when used on a STRING LENGTH STRING variable has effect only under conditions outlined in the MOVE MOVE statement, since the length of a string is determined dynamically under all other conditions. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:21 LABEL DECLARATIONS LABEL DECLARATIONS Note that there is no explicit declaration for identifiers to be used as statement-labels. This causes an ambiguity in the scope rules as stated. Consider the following example: : : goto label.1; : : begin : label.1: : : goto label.1; : : end; : : goto label.1; : : label.1: : : The first goto will be compiled as a forward reference to 'label.1'. This forward-reference will be resolved when the 'label.1' declaration is encountered inside the begin-block. The second 'goto' is inside the block in which 'label.1' is declared, and is a reverse-reference, and is compiled as expected. When the 'end' statement is encountered, the declaration of 'label.1' is removed from the symbol-table. When the third 'goto' is encountered, it references a label which is not in the symbol- table and is compiled as a forward-reference. When the second declaration of 'label.1' is encountered, the forward-reference is resolved. This results in the situation where two 'goto's (the first and third) reference the same label, but are compiled to branch to different places. This can be easily avoided by always having unique names for all identifiers used as labels. The only way around this ambiguity would be to allow an explicit LABEL LABEL declaration to define the scope of a label, and this may be included as a feature in a future version of PARASOL. If is is included, it will be optional so that any programs compiled with previous versions of PARASOL will still compile in the same manner. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:22 CP/M RESERVED MEMORY USAGE CP/M RESERVED MEMORY USAGE Any of the CP/M reserved memory areas may be accessed by declaring appropriate EXTERNAL variables. The majority of EXTERNAL PARASOL statements have no effect on this part of memory, but if the program uses any part of this area, the programmer should be aware that the following statements may modify it: REMOVE REMOVE RENAME RENAME FIND (except when a FILE is used as the FIND FILE object of the statement, instead of a string-literal or string-variable.) Also the programmer should be aware that the OPEN statement OPEN uses data from this area (the default-fcb at address ^h5c), on the first OPEN (only) of a file containing the FILE1 or FILE2 OPEN FILE1 FILE2 clause. So, for the program to work as intended, all files which use the FILE1 or FILE2 clauses should be OPENed prior to using FILE1 FILE2 OPEN the REMOVE, RENAME, or FIND statements. REMOVE RENAME FIND Also the compiler generates code which uses the CP/M default-dma record at address ^h80 for all directory operations during any disk-file related activities, and since this is also the area used for console-command-line storage, the command-line should be processed or saved in another location prior to executing any disk-related statements. In general, if the contents of this area of memory are of importance to yuor program, you should move a copy of it to local storage in the first statement of your program. This will insure that you get a non-corrupted copy of it. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:23 ABBEVIATIONS USED FOR VARIABLE-TYPES ABBEVIATIONS USED FOR VARIABLE-TYPES The following abbreviations will be used in the subsequent pages to indicate the variable types allowed in the position indicated: bcd A decimal variable. It may be BCD or BCD-POINTER. BCD BCD-POINTER bin A binary variable. It may be BYTE, WORD, BYTE- BYTE WORD BYTE- POINTER, or WORD-POINTER. POINTER WORD-POINTER num A numeric variable, it may be any of the types allowed for 'bcd' or 'bin'. str A string variable. It may be STRING or STRING- STRING STRING- POINTER. POINTER cnst A constant. This may be expressed in decimal or any other radix(base) which is convenient. Note that a constant may also be specified with a 1- or 2-character string-literal, a '#' followed by an identifier, or an identifier declared as a constant in a SETstatement. SET dcnst A decimal constant. This is generally only required when appearing in a statement with a BCD variable. BCD lit A string-literal enclosed in quotes(") or " apostrophes('). ' rec A RECORD variable. RECORD bit A BIT variable. BIT id Any identifier. This may be either a statement- label, or a variable-name. var Any variable identifier. All other variable-types are spelled-out and are self- explanatory. Note that the abbreviations given above may be followed by a dash and a number when more than one occurrs in a statement in order to allow the text to point out specific details about the position indicated. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:24 ACCEPT statement ACCEPT statement {lit} [ {lit}] ACCEPT {str} [,{str}]... ______ _ ACCEPT ______ {rec} [ {rec}] If a string-literal is used, it is displayed as a prompt for a subsequent string or record variable. This statement uses the CP/M bufferred console input call (function 10). To meet the requirements of CP/M, the STRING variable which is to accept the value must be at least two bytes longer than the longest input string which is to be accepted. All CP/M line-editing features are available to the operator while responding to an ACCEPT. This statement invokes CP/M ACCEPT function 10 (read console buffer). See the CP/M programmer's guide for further information. EXAMPLES ________ : : string con.in.string 42; { max input length is 40 } : : accept "Enter your name",con.in.string; display "Your name is:",con.in.string; : : PARASOL language manual Copyright (C) 1982, Para-Soft Pg:25 ADD statement ADD statement ADD {cnst-1} TO {cnst-2} [ GIVING num-3] ___ ______ ADD TO GIVING ___ ______ {num-1 } {num-2 } The value of (cnst-1/num-1) is added to (cnst-2/num-2) and the result is stored in num-2 if no GIVING clause is present. If GIVING a GIVING clause is present, the result is stored in num-3. GIVING If cnst-2 is used, the GIVING clause MUST be used. GIVING If one or both source fields are 16-bit, and the destination field is 8-bit, a truncation warning will be printed on the compile listing. For binary addition: If all variables are 8-bit, the addition is performed modulus 256, if any variable is 16-bit, the addition is performed modulus 65536. For decimal addition, the addition is done to the modulus of the maximum size of the BCD variable. BCD If both cnst-1 and cnst-2 are used, the addition is done at compile-time, and the statement is optimised to a MOVE statement. MOVE If either cnst-1 or cnst-2 is zero, the statement is optimised to a MOVE statement. MOVE EXAMPLES ________ : : string test.string 30 value "ABCDEFGHIJKLM"; pointer to byte test.str.bp value #test.string; byte test.byte; bcd test.bcd.1, test.bcd.2; : : add 5 to #test.string giving test.str.bp; { Note that this will be optimised } { Note that since 'test.str.bp' is not } { preceded by @, that it is treated as } @ { a WORD variable for this statement } WORD move @test.str.bp to test.byte; { This will move 'F' } add 3 to test.byte; { 'test.byte' now contains 'I' } add 5 to test.bcd.1 giving test.bcd.2; add test.bcd.1 to 5 giving test.bcd.2; { Both of the above statements do the same thing } : : : PARASOL language manual Copyright (C) 1982, Para-Soft Pg:26 AND/OR/XOR statements AND/OR/XOR statements AND {cnst-1} WITH {cnst-2} [GIVING bin-3] ___ ______ AND WITH GIVING ___ ______ {bin-1 } {bin-2 } The specified operation is performed on the variables in a bit-by-bit manner. The result of the operation is stored in bin- 3 if the GIVING clause is present. If the GIVING clause is not GIVING GIVING present, and either cnst-1 or cnst-2 is used, the result is stored in the bin variable specified. If both bin-1 and bin-2 are specified, the result is stored in bin-1 when no GIVING GIVING clause is present. The receiving field determines whether the operation is done as an 8- or 16-bit operation. If cnst-1 and cnst-2 are both used, the GIVING clause must GIVING be used. Also when cnst-1 and cnst-2 are both used, the operation is done at compile-time, and the statement is optimised to a MOVE statement. MOVE If the receiving field is 16-bit, and one or both source fields are 8-bit, the 8-bit fields are treated as 16-bit fields with a hi-order byte of binary zeros. EXAMPLES ________ : : byte a value ^b10100011, b value ^b01011100, c value 0; word i value ^b1100110011001100, j value ^b0110011001100110, k value 0; : : : and a with ^b00001111 giving c; {c now contains ^b00000011} and a with b giving c; {c now contains zero} or a with b giving c; {c now contains ^b11111111} xor i with j giving k;{k now contains ^b1010101010101010} : : { Example of a 'status-wait' loop } do input c from control.port; and c with ^h01; od until c <> 0; {infinite loop until bit is set} : { This could be done more simply using the } { AND expression operator as follows } do input c from control.port; od until c and ^h01; PARASOL language manual Copyright (C) 1982, Para-Soft Pg:27 APPEND statement APPEND statement APPEND {str-1} TO {str-2} ______ APPEND TO ______ {lit } The value of (lit/str-1) is appended to the end of str-2. Note that no check is done that the resulting string is within the limits declared for str-2. EXAMPLES ________ : : string a 80 value 'This is', b 20 value 'a test'; : : append b to a; {a now contains 'This isa test'} {-- This should have been done as follows --} append " " to a; append b to a; {now a would contain 'This is a test'} : : PARASOL language manual Copyright (C) 1982, Para-Soft Pg:28 BCD variable declaration BCD variable declaration BCD bcd-1 [VALUE dcnst] [, bcd-2 [VALUE dcnst]]... ___ _____ _ _____ BCD VALUE VALUE ___ _____ _____ This statement declares BCD variables. Each variable will require 8 bytes of storage with the standard BCD variable length. For non-standard BCD lengths, the size can be computed by dividing the maximum number of digits by 2, rounding up to the next whole number if the maximum number of digits was odd, and adding 1. The storage format of BCD variables is 'compatible' with the Intel-8087 numeric co-processor when the maximum number of digits is 16 (note that this is not the standard number of digits in PARASOL). The hi-order bit of the first byte is the sign (0=+ 1=-), the low-7 bits of the first byte are ignored, and the number is stored in absolute-magnitude format in the remaining bytes as packed bcd digits. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:29 BEGIN statement BEGIN statement BEGIN statement-list END _____ ___ BEGIN END _____ ___ This statement-block may appear anywhere that a single statement is allowed. The statement-list is of the following format: BEGIN BEGIN [ data declarations ] [ procedure declarations ] [ executable statements ] END END Any of the above items are optional, and may be omitted. If either data-declarations, or procedure-declarations are present, the compiler will insert code in the object-code to jump around them when the BEGIN-block is 'fallen-into'. Note that in BEGIN accordance with the identifier-scope rules previously given, any data or procedures declared inside a BEGIN-block may be BEGIN referenced by name only from within the BEGIN-block. They will BEGIN be undefined outside the block. The EXITBEGIN statement is allowed as any of the statements EXITBEGIN in the executable statements, and will branch to the statement following the END statement. END EXAMPLES ________ test.prog: begin : : byte switch.1; : : move 0 to switch.1; : : begin string local.string 20; : : if switch.1 <> 0 then exitbegin fi; { This statement will 'goto' un.needed.label } : : end; {end of block} un.needed.label: : : end; {end of program} PARASOL language manual Copyright (C) 1982, Para-Soft Pg:30 BIT variable declaration BIT variable declaration BIT [id-1] [VALUE {TRUE }] [, [id-2] [VALUE {TRUE }] ]... ___ _____ ____ _____ ____ BIT VALUE TRUE VALUE TRUE ___ _____ ____ _____ ____ {FALSE} {FALSE} _____ _____ FALSE FALSE _____ _____ { 0 } { 0 } 0 0 { 1 } { 1 } 1 1 This statement will declare a BIT variable. Bits are allocated starting with the high-order bit of a byte. Declarations need not be done in the same statement in order to be allocated in the same byte. Any BIT variable which is not BIT given a value is compiled as though a zero (FALSE) value had been assigned. EXAMPLES ________ : : byte bit.mapped.byte value ^h05; redefine bit.mapped.byte; bit bit.7 value true, bit.6 value false, bit.5 value true, bit.4; bit bit.3, bit.2, bit.1, bit.0; { this will initialise bit.mapped.byte to ^ha5 } endredef; : : move true to bit.1; {bit.mapped.byte now contains ^ha7} if bit.3 then display "bit.3 is true" else display "bit.3 is false" fi; : : PARASOL language manual Copyright (C) 1982, Para-Soft Pg:31 BYTE variable declaration BYTE variable declaration BYTE [id-1] [ VALUE cnst-1 ] [,[id-2] [VALUE cnst-2] ]... ____ _____ _ _____ BYTE VALUE VALUE ____ _____ _____ This statement declares an 8-bit binary numeric variable. Any BYTE's not given a VALUE will be initiallized to zero. BYTE VALUE PARASOL language manual Copyright (C) 1982, Para-Soft Pg:32 CALL statement CALL statement CALL {label} ____ _____ CALL ____ {cnst } ____ {id } __ This statement compiles a machine-code CALL instruction. For maximum flexibility, the address referenced may be not only a label, but a numeric constant, or a variable identifier. This allows CALLing routines stored in ROM (with the constant option) CALL or user implementation of machine-code routines in data-areas. Program execution will transfer to the address specified, and when an EXIT statement, or a machine-level RETurn EXIT instruction, is encountered, program execution will resume at the statement following the CALL statement. Note that if a label is CALL used, and that label is a procedure, that the compiler automatically inserts an EXIT statement following the procedure, EXIT so 'falling-out' of a procedure is all that is required to return from a procedure. If the label is the name of a SEGMENTED procedure, the SEGMENTED compiler will call a built-in routine to handle the overaly. If the CALLed procedure is already in memory, it is simply branched- to. If it is not in memory, it is first loaded from disk. If a label is used, it need not be declared prior to this statement. (forward-reference is allowed on the CALL statement). CALL The exception to this is SEGMENTED procedures. They may NOT be SEGMENTED forward referenced. EXAMPLES ________ : : procedure kettle.black: begin : : end; : : pot: call kettle.black; call another.way; : : goto end; {to prevent 'falling-into' routine below} : : another.way: : : exit; {required, since this is not declared} { as a procedure } : : end; PARASOL language manual Copyright (C) 1982, Para-Soft Pg:33 CLOSE statement CLOSE statement CLOSE file-id [REMOVE] [ERROR statement] _____ ______ _____ CLOSE REMOVE ERROR _____ ______ _____ This statement invokes the CP/M function 16 (close-file). If the REMOVE option is used, CP/M function 19 (delete-file) will REMOVE also be invoked. If the file is not a disk-file, the REMOVE and ERROR options REMOVE ERROR are invalid, and this statement will do nothing. If the file is a DISK TEXT OUTPUT file, this statement will DISK TEXT OUTPUT generate code which will insert end-of-file characters (hex code ^h1a) onto the end of the text prior to CLOSEing the file. CLOSE The FILE STATUS of file-id will be set to the value returned FILE STATUS by CP/M. If the ERROR clause is present, and the CP/M status returned ERROR is ^hff, the ERRORstatement will be executed, otherwise, program ERROR execution continues with the next statement following the CLOSE CLOSE statement. for examples, see the FILE statement ___ _________ ___ ___ ____ _________ FILE ____ PARASOL language manual Copyright (C) 1982, Para-Soft Pg:34 CONVERT statement CONVERT statement CONVERT str TO {UPPER} CASE _______ _____ CONVERT TO UPPER CASE _______ _____ {LOWER} _____ LOWER _____ This form of the CONVERT statement translates the string CONVERT given into upper-case or lower-case. Only alphabetic characters are affected; numerics and symbols are not changed by this statement. CONVERT bcd TO bin _______ CONVERT TO _______ This form of the CONVERT statement converts from BCD format CONVERT BCD to binary format. If the bin variable is 8-bit (BYTE or BYTE- BYTE BYTE- POINTER) a truncation warning is produced. POINTER CONVERT bin TO bcd _______ CONVERT TO _______ This form converts binary into BCD format. BCD CONVERT bcd TO str _______ CONVERT TO _______ This form converts BCD format into STRING format BCD STRING CONVERT str TO bcd [ERROR statement] _______ _____ CONVERT TO ERROR _______ _____ This form converts a STRING to BCD format. See binary-to- STRING BCD string conversion below for a description of the ERROR clause. ERROR { OCTAL } _____ OCTAL _____ CONVERT bin TO {HEXADECIMAL} str _______ ___________ CONVERT TO HEXADECIMAL _______ ___________ { DECIMAL } DECIMAL This form of the CONVERT statement converts from binary CONVERT format to string format. The radix (base) of the conversion may be specified, with DECIMAL being the default. HEXADECIMAL, DECIMAL HEXADECIMAL DECIMAL, and OCTAL may be abbreviated HEX, DEC, and OCT DECIMAL OCTAL HEX DEC OCT respectively. Both OCTAL and HEX conversions are done with NO OCTAL HEX leading-zero suppression; OCTAL gives 6 digits, and HEX gives 4 OCTAL HEX digits. DECIMAL conversion IS zero-suppressed, and only the DECIMAL number of significant digits present in the number are produced (always at least 1 digit) { OCTAL } _____ OCTAL _____ CONVERT {HEXADECIMAL} str TO bin [ERROR statement] _______ ___________ _____ CONVERT HEXADECIMAL TO ERROR _______ ___________ _____ { DECIMAL } DECIMAL This form of the CONVERT statement converts from string CONVERT format to binary format. As above, OCT, HEX, and DEC are OCT HEX DEC acceptable abbreviations. This statement will ignore 'overflow' conditions. The result is computed to the modulus of the bin variable. The ERROR statement is provided to detect invalid ERROR characters in the string being formatted. The conversion will terminate on the first character in the string which is not valid for the specified radix. If this character is not null (if the entire string was not used in the conversion), The ERROR ERROR statement will be executed if specified; if no ERROR statement is ERROR PARASOL language manual Copyright (C) 1982, Para-Soft Pg:35 CONVERT statement CONVERT statement present, execution continues with the statement following the CONVERT statement. If the first character in the string is CONVERT invalid for the specified radix, a value of zero is stored in the bin varible. If the bin variable is 8-bit (BYTE or BYTE-POINTER, BYTE BYTE-POINTER a truncation warning is produced). EXAMPLES ________ : : byte wk.byte value 10; word wk.word value 1000; string wk.str value "1234 This is a test 5678"; bcd wk.bcd value -21; : : convert wk.str to upper case; {wk.str now contains '1234 THIS IS A TEST 5678'} convert wk.str to lower case; {wk.str now contains '1234 this is a test 5678'} convert wk.str to wk.word; {wk.word now contains 1234 in binary} convert wk.str to wk.word error display "this will show up"; {the ERROR clause will be executed} ERROR {wk.word still will get the value 1234} convert wk.byte to octal wk.str; {wk.str = '000012'} convert wk.bcd to wk.str; {wk.str = '-21'} convert wk.str to wk.word; {wk.word gets zero since the minus is not allowed} { for binary (all binary values are unsigned) } PARASOL language manual Copyright (C) 1982, Para-Soft Pg:36 COPY statement COPY statement COPY file-specifier ; ____ _ COPY ; ____ _ This statement copies text from a disk file into the source program at the point the COPY statement is encountered. The text COPY copied in is treated exactly as though it were being read from the source file. The distributed version of the compiler allows COPYs to be nested once. You can COPY file-1, file-1 may then COPY file-2, but file-2 cannot COPY another file. Special versions of PARASOL are available which extend this level, if needed. The semicolon following the COPY statement is required, and COPY the COPY should be the only statement on the source line. COPY The file-specifier is a CP/M file name enclosed in quotes or apostophes. A drive-specifier may be present, if desired. If the PARASOL compiler cannot locate the file to be COPYed, on the COPY specified drive (default drive if none specified), it will suspend compilation and ask for another filename for the library. If a compile-listing is being generated, the COPY statement COPY will be listed, followed by the text in the disk file which was copied. If line-numbers are being printed on the compile- listing, the numbering of source lines will be interrupted during the listing of the COPYed text, and that text will have line COPY numbers of the form 'A9999' starting with 'A0001'. The numbering of source lines will resume following the COPY operation. This COPY allows the maximum amount of correlation between the line-numbers printed on the compile-listing, and the line-numbers used by 'ED', the CP/M text editor utility. When COPYs ar nested, the nested COPY will have line numbers of the form "B9999" (starting with "B0001"). EXAMPLES ________ Suppose you had a disk file "CONIN.LIB" which contained the following text: record terminal.info; byte terminal.number, terrminal.count, terminal.type; string con.in.string 81; endrec; (^Z) (end-of-file character) Then you could write a source program of the form: : : copy "CONIN.LIB"; : : accept con.in.string; display con.in.string; add 1 to terminal.count; : : PARASOL language manual Copyright (C) 1982, Para-Soft Pg:37 interrupt-control statements interrupt-control statements {DISABLE} INTERRUPTS _______ DISABLE INTERRUPTS _______ {ENABLE } ______ ENABLE ______ This generates the assembler instructions DI and EI respectively. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:38 DISPLAY statement DISPLAY statement DISPLAY {lit} [, {lit} ]...[,;] _______ _ __ DISPLAY , ,; _______ _ __ {str} {str} This statement displays string-literals and string-variables onto the console device. All items appearing in a single DISPLAY DISPLAY statement will be displayed contiguously with a carriage- return/linefeed following the last item. If it is desired to suppress the final cr/lf, the DISPLAY statement should end with a DISPLAY comma. If an ending comma is used, the semicolon to terminate the statement is required so that the compiler will be able to determine where the statement ends. Note that 'display;' causes no action. To cause display of nothing but a cr/lf, use 'display "";'. EXAMPLES ________ : : string wk.str 10; byte test.count; : : display "There are ",; {note comma to suppress cr/lf} if test.count = 0 then display "no",; else convert test.count to dec wk.str; display wk.str,; fi; display " entries present"; {if test.count = 0 this will display: } { There are no entries present } {if test.count = 5 this will display: } { There are 5 entries present } PARASOL language manual Copyright (C) 1982, Para-Soft Pg:39 DIVIDE statement DIVIDE statement DIVIDE {cnst-1} BY {cnst-2} ______ DIVIDE BY ______ {num-1 } {num-2 } [ GIVING num-3] ______ GIVING ______ [ REMAINDER num-4] _________ REMAINDER _________ This statement divides the value of (cnst-1/num-1) by the value of (cnst-2/num-2). If cnst-1 is specified, the GIVING GIVING option must be used. If no GIVING option is used, the result is GIVING stored in num-1. If the GIVING option is used, the result of the GIVING divide is stored in num-3. If the REMAINDER clause is used, the remainder from the REMAINDER divide operation is stored in num-4. If cnst-1 and cnst-2 are both specified, the divide operation is done at compile-time, and this statement is optimised to a MOVE statement. MOVE Pointer-variables, not preceded by '@', are treated as WORD WORD variables by this statement. If the receiving-variable is 8-bit, a truncation warning will be shown on the compile listing. All binary divide operations are done as 16-bit operations, even if all variables involved are 8-bit. BCD and binary values cannot be mixed in this statement. BCD All values must be binary, or all values must be BCD. BCD PARASOL language manual Copyright (C) 1982, Para-Soft Pg:40 DO and WHILE statements - looping constructs DO and WHILE statements - looping constructs [WHILE cond-1] [DO] _____ __ WHILE DO _____ __ statement-list [OD] [UNTIL cond-2] __ _____ OD UNTIL __ _____ This statement executes statement-list repetitively, optionally depending on conditional termination of the repetition. The WHILE clause causes cond-1 to be evaluated prior to each WHILE execution of statement-list. If cond-1 is true, statement-list is executed. If cond-1 is false, execution continues following the OD or UNTIL clause. OD UNTIL The UNTIL clause causes cond-2 to be evaluated after each UNTIL execution of statement-list. If cond-2 is true, execution continues with the statement following the OD or UNTIL clause, if OD UNTIL cond-2 is false, execution continues with the WHILE or DO WHILE DO statement. The DO is required if the WHILE clause is omitted. The OD DO WHILE OD is required if UNTIL clause is omitted. UNTIL If both the WHILE and UNTIL clauses are present, execution WHILE UNTIL of statement-list terminates whenever cond-1 becomes false, OR __ cond-2 becomes true. If neither the WHILE nor the UNTIL clauses WHILE UNTIL are present, execution of statement-list continues indefinitely (infinite loop), unless there is a provision within statement- list to terminate the loop. (EXITDO) The EXITDO statement may appear as a statement within EXITDO statement-list. If an EXITDO is executed, program execution EXITDO immediately resumes following the OD or UNTIL clause. OD UNTIL EXAMPLES ________ : : procedure compute.power: begin move 1 to result; while exponent > 0 do multiply result by number; subtract 1 from exponent; od; end; : : do accept "Enter your guess ('0' to quit);",con.in.rec; if con.in.string = '0' then exitdo; fi; if con.in.string = my.guess then display "You are correct"; else display "Wrong - try again"; fi; od; PARASOL language manual Copyright (C) 1982, Para-Soft Pg:41 EDIT statement EDIT statement EDIT {lit-1} WITH {lit-2} [GIVING str-3] ____ ______ EDIT WITH GIVING ____ ______ {str-1} {str-2} This statement is designed to format data for display on an output device, usually a terminal or printer, although this is by no means the only use for this statement. (Str-2/lit-2) specifies a 'picture' to use for the editing operation. The movement of characters, insertion of characters, etc. is controlled by the characters present in the picture string. If the GIVING clause is present, the result is stored in GIVING str-3. If the GIVING clause is not present, str-1 must be GIVING specified, and str-1 will receive the edited data as well as supply the raw data to be edited. The length of the receiving string (field-width) is determined entirely by the picture string, there is NO protection against this exceeding the declared length of the destination string. The picture string is composed of the following characters. These characters have the effects described to the right of the character: L Left-justify the receiving string. L If L is specified, it must be the first L character in the picture-string. Left-justification is default if the picture- string starts with 'X' or ' '. R Right-justify the destination-string. R If present, this must be the first character in the picture-string. Right-justification is the default if the picture does not begin with either 'L', 'X', or ' '. X This will cause one character to be moved from X The source-string to the destination-string. The cahracter is moved exactly 'as-is'. 9 This will cause one numeric digit to be moved from 9 the source-string to the destination-string. The results of moving non-numeric characters with '9' are undefined, although it will generally behave as ax "X". (space) This will cause a blank character to be inserted into the destination-string. No characters are skipped-over in the source-string as a result of this. Z This is a zero-suppressed numeric-character Z move. If any non-zero, non-blank characters have been moved during the execution of this statement, this will be treated as a '9' picture-character. If there have been no non-zero, non-blank characters moved, and the current character to be moved is PARASOL language manual Copyright (C) 1982, Para-Soft Pg:42 EDIT statement EDIT statement zero or blank, move a blank to the destination- string, otherwise move the current character to the destination-string. $ If the NEXT character to be moved (not the $ current character) is the first non-blank,non-zero character to be moved to the destination-string, move a '$' to the destination-string instead of the current character. If any non-zero,non-blank characters have already been moved, or if the current character is non-zero,non-blank, move the current character to the destination-string. If no non-zero,non-blank characters have been moved, and both the current and next characters are blank or zero, move a space to the destina- tion-string. . (period) Insert a period (decimal-point) into . the destination-string, without skipping over any characters in the source-string. , (comma) If any non-blank,non-zero characters , have been moved, insert a comma, otherwise insert a space into the destination-string. + (plus sign) If this is the last character in the + picture-string, insert a '+' or '-' into the destination-string. Whether a '+' or '-' is inserted depends on whether a '-' was encountered in the source-string while moving previous characters. If this is not the last character in the picture-string, it is treated the same as the '$', except that the character inserted will be '+' or '-' instead of '$'. - (minus sign) This is handled the same as the plus - sign, except that only '-' will be inserted if a '-' was encountered in the source string. Other- wise, a space will be inserted. Ix (x represents any character) Insert the character I x into the destination-string without skipping x over any characters in the source-string. Anything else encountered in the picture-string is treated as an 'X'. The '$', '+', and '-' are mutually exclusive unless one is leading(floating), and another is trailing (example: "$$$,$$9.99- " is valid). If a leading (floating) sign is used, it must appear in a position in the picture-string corresponding to the position in the source-string where a '-' may be encountered. For example: editing '-1' with '---,-99' will result in ' 01', since the minus sign in the source-string appeared where there was a '9' in PARASOL language manual Copyright (C) 1982, Para-Soft Pg:43 EDIT statement EDIT statement the picture-string. EXAMPLES ________ : : string todays.date 7 value '123180'; string picture.z.9 20 value 'ZZZ,ZZ9.99'; string total.amt 15 value '654321'; string wk.str 81; : : edit total.amt with picture.z.9 giving wk.str; {wk.str now contains ' 6,543.21'} edit todays.date with "99I/99I/99" giving wk.str; {wk.str now contains '12/31/80'} : : PARASOL language manual Copyright (C) 1982, Para-Soft Pg:44 EXECUTE statement EXECUTE statement EXECUTE {str-1} [USING {str-2}] [ERROR stmt] _______ _____ _____ EXECUTE USING ERROR _______ _____ _____ {lit-1} {lit-2} This statement causes another specified program to be loaded into memory and executed. There is no built-in provision for maintaining variable values, etc. between programs, although these may be implemented easily using EXTERNAL variables. The EXTERNAL EXECUTE statement does not affent the CP/M default-DMA buffer at EXECUTE address ^h80, unless the USING clause is used. This buffer may USING be used to pass values between programs if desired. The program is assumed to be in standard CP/M object format. (Str-1/lit-1) is the name of the program specified in standard file-name format. (Str-2/lit-2) is the command-line to pass to the program. If the USING caluse is not used, the command-line passed to the USING program is undefined. Note that the USING clause passes ONLY the USING command-line. It does not set the CP/M default-fcb at address ^h5c as CP/M does, so any programs which use this (PARASOL programs using FILE1 and/or FILE2) will need modification. The ERROR clause provides program recovery if the specified ERROR program cannot be located. If the ERROR clause is omitted and ERROR the program cannot be found, a run-time error ("FILE EXECUTE ERROR") will be displayed on the console, and program execution will terminate. If the ERROR statement is included, and the ERROR program cannot be found, the ERROR statement is executed, and ERROR program execution resumes following the EXECUTE statement. EXECUTE EXAMPLES ________ : : string next.prog.id 13; : : execute next.prog.id error display next.prog.id," is missing"; : : execute "PIP.COM" using "B:=A:*.SAV" error display "reload PIP and run backup again"; : : PARASOL language manual Copyright (C) 1982, Para-Soft Pg:45 EXIT statements EXIT statements EXIT ____ EXIT ____ EXITBEGIN _________ EXITBEGIN _________ EXITDO ______ EXITDO ______ EXITSWITCH __________ EXITSWITCH __________ Each of these statements causes control to pass out of the associated program-structure. The EXIT statement is different EXIT from the other statements in that its point of transfer is determined at run-time, while the other EXIT- statements are EXIT- fully determined at compile time. The EXIT statement generates a machine RETurn instruction, EXIT and will exit to the statement following the last CALL statement CALL executed. If the machine stack has been manipulated, or wiped- out accidentally, the results of executing the EXIT statement are EXIT undefined. The compiler inserts an EXIT statement following each EXIT PROCEDURE, and the normal exit from a procedure is to 'fall out' PROCEDURE of the procedure. The EXIT statement provides an alternate EXIT method of leaving a procedure. The other EXIT- statements are valid ONLY within their EXIT- associated structure, and will cause a syntax error if encountered in a program outside of that structure. Each causes an immediate branch to the statement following the structure- ending statement (END, ENDCASE, OD, FI, and ENDSWITCH). END ENDCASE OD FI ENDSWITCH for examples, see the CALL, BEGIN, CASE, DO, IF, and SWITCH CALL BEGIN CASE DO IF SWITCH statements. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:46 EXTERNAL variable declaration EXTERNAL variable declaration EXTERNAL type name ADDRESS cnst-1 [LENGTH cnst-2] ________ _______ ______ EXTERNAL ADDRESS LENGTH ________ _______ ______ 'type' may be any of the following: BCD BCD BCD POINTER BCD POINTER BYTE BYTE BYTE POINTER BYTE POINTER FIELD * FIELD LABEL LABEL RECORD * RECORD STRING * STRING STRING POINTER STRING POINTER WORD WORD WORD POINTER WORD POINTER *The LENGTH option is valid LENGTH only for the types marked with an asterisk. This statement declares an identifier which is outside the bounds of the program. This may be used to access any operating- system function (by using the MCALL statement), or to allocate a MCALL section of memory to use as a 'common' area to pass data between programs. The identifier defined in this statement may be referenced in all respects as a normal identifier of the type declared. EXAMPLES ________ : : external byte i.o.byte address 3; {--CP/M I/O-byte--} external label boot address 0; {--warm-start entry--} external label entry address 5; {--CP/M BDOS entry--} external word himem.limit address 6; external record default.dma address ^h80 length ^h80; external record default.fcb address ^h5c length 35; : : mcall entry using 13; {--CP/M reset-disk system call--} mcall entry using 11 giving ,,,con.stat; {--get console status--} : : Note the definition of "himem.limit" above. This references the base address of the CP/M BDOS, which is also the limit for programmable memory when running under CP/M. This is useful when using data stored in HIMEM to determine whether any available HIMEM memory exists. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:47 FIELD data declaration FIELD data declaration FIELD id-1 size [,id-2 size]... _____ FIELD _____ This statement declares a data storage area of type FIELD. FIELD A field is similar to a STRING in many respects, but is STRING incompatible with it for most statements. A FIELD has no null- FIELD byte terminator, therefore its length is static and fully determined at compile-time, as opposed to a STRING which has a STRING null byte terminator which determines its dynamic length. FIELDs are designed for use in print-line formatting, disk FIELD record I/O, and user coded 'substring' functions, situations where the null-byte string-terminator would not be desired. See the MOVE statement for usage of FIELDs. ___ ___ ____ _________ ___ _____ __ ______ MOVE FIELD ____ _____ PARASOL language manual Copyright (C) 1982, Para-Soft Pg:48 FILE declaration FILE declaration FILE id-1 ____ FILE ____ [, BLOCKED {cnst-1}] _______ BLOCKED _______ [, BUFFER {str-1 }] ______ BUFFER ______ {rec-1 } {field-1} [, CON] ___ CON ___ [, DISK] ____ DISK ____ [, FILE1] _____ FILE1 _____ [, FILE2] _____ FILE2 _____ [, KEY id-2] ___ KEY ___ [, LST] ___ LST ___ [, NO BUFFER] __ ______ NO BUFFER __ ______ [, PRN] ___ PRN ___ [, PUN] ___ PUN ___ [, RANDOM] ______ RANDOM ______ [, RDR] ___ RDR ___ [, RECORD {str-2 }] ______ RECORD ______ {rec-2 } {field-2} {byte-2 } [, STATUS id-3] ______ STATUS ______ [, TEXT] ____ TEXT ____ [, TTY] ___ TTY ___ [, VALUE {str-3}] _____ VALUE _____ {lit-3} This statement declares a file for the program to use. A wide variety of file-types are supported by PARASOL. The file may be character-oriented, or record-oriented. In the current release, only DISK files may be record-oriented, however, DISK DISK DISK files may be character-oriented if desired. The BLOCKED clause is valid only for disk files. It BLOCKED determines how the records are allocated on disk. A file containing a BLOCKED clause may have a record of any length. BLOCKED There are two different options available with the BLOCKED BLOCKED clause: If cnst-1 is non-zero, (for example, 3), the records are grouped together three at a time, and each group of three records will begin on a sector boundary, even if the total length of three records is longer than one sector. This method is generally not preferred, but has been provided to allow compatibility with certain other languages. If cnst-1 is zero, the records are strung-together one after the other. This is compatible with the way in which MICROSOFT BASIC stores records in random files. This is the preferred method both because of MBASIC compatibility and due to the maximum storage density which it provides. The BUFFER clause specifies a buffer area for use in DISK BUFFER DISK TEXT files. The BUFFER clause is ignored for all other file- TEXT BUFFER types. If the size of (str-1/rec-1) is not an even multiple of 128 bytes, the size used is the next smaller even multiple of 128 bytes. Having a large buffer reduces disk-head-seeking time when PARASOL language manual Copyright (C) 1982, Para-Soft Pg:49 FILE declaration FILE declaration using multiple DISK TEXT files at the same time. DISK TEXT The CON clause specifies that the file is assigned to the CON system console. A record of type BYTE only is allowed. The file BYTE may be read or written, and any OPEN or CLOSE statements for the OPEN CLOSE file will be ignored. If a file is always going to go to the ______ console, it is generally simpler to use ACCEPT and DISPLAY ACCEPT DISPLAY statements. Declaring a file to be assigned to the console has the flexibility of allowing the file to be assigned to the disk, or printer, etc. by changing only the CON clause to the device CON desired. The DISK clause specifies the file to be assigned to disk. DISK The file may be either record-oriented, or character-oriented. A character-oriented file is declared by specifying TEXT in the TEXT file statement, and by having a RECORD of type BYTE. A record- RECORD BYTE oriented file is declared by not specifying TEXT. ___ TEXT The FILE1 and FILE2 clauses specify that a DISK file will FILE1 FILE2 DISK use the CP/M default-fcb at location ^h5c to determine the name of the file. FILE1 and FILE2 are valid only with DISK files, and FILE1 FILE2 DISK ignored for other file-types. Note that the FIND, REMOVE, FIND REMOVE RENAME, and EXECUTE statements may alter the CP/M default-fcb, RENAME EXECUTE therefore, any file having the FILE1 or FILE2 clauses should be FILE1 FILE2 OPENed prior to executing any of these statements. The name from OPEN the CP/M default-fcb is used ONLY on the FIRST OPEN of a file. OPEN Any subsequent OPENs are treated as though the file had been OPEN declared with the name given by the CP/M default-fcb at the time the first OPEN was done. If a 'VALUE string-id' clause is used, OPEN VALUE it will be superceded by the FILE1 or FILE2 on the FIRST OPEN _____ FILE1 FILE2 OPEN only, after that, the value of 'string-id' will specify the name of the file. For example, if the file declaration contains "VALUE 'TEST.FIL'", and the program is executed with a FILE-1 value of "ABC", the actual name used will be "ABC.FIL". The KEY clause is valid only on DISK RANDOM files, and is KEY DISK RANDOM ignored for all other file-types. The idenifier specified in the KEY clause should not be declared prior to the file, this clause ______ ___ KEY declares id-2 to be a WORD variable located within the file- WORD control-block (fcb) at the position used by CP/M to specify the random-record-number. The record number may range from 0 to 65535. The LST and PRN clauses are eqiuvalent, and declare the file LST PRN to use the system printer (CP/M LST: device). The file can only be written-to, not read. The NO BUFFER clause is used only for blocked-mode files. NO BUFFER If NO BUFFER is specified, then the compiler will not allocate a NO BUFFER sector buffer for the file, and all READ statements will behave READ as though they had the FRESH clause. The generated program will FRESH use the CP/M default-DMA buffer at address 80h for a temporary buffer when doing file I/O for any file having the NO BUFFER NO BUFFER clause. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:50 FILE declaration FILE declaration The PUN clause declares the file to use the system punch PUN (CP/M PUN: device). The file can only be written-to, not read. The RANDOM clause defines the file to be a RANDOM file. RANDOM RANDOM This clause should be used only on DISK record-oriented files, DISK and should be used in conjunction with the KEY clause. KEY The RDR clause declares the file to be assigned to the RDR system reader (CPM RDR: device). The file may only be read-from, not written-to. The RECORD clause specifies the data-interface area o f the RECORD file. For TEXT (character-oriented) files, the RECORD should be TEXT RECORD of type BYTE. For non-TEXT files, the RECORD should be a FIELD, BYTE TEXT RECORD FIELD RECORD, or STRING variable with a length of 128 bytes, unless the RECORD STRING BLOCKED clause is used. BLOCKED The STATUS clause (like the KEY clause), gives a name to a STATUS KEY data area within the fcb, and should not be declared prior to declaring the file. The STATUS-variable is of type BYTE, and has STATUS BYTE meaning only for DISK files. It is given the value returned by DISK the CP/M BDOS following any OPEN, CLOSE, READ, or WRITE involving OPEN CLOSE READ WRITE the file. For TEXT DISK files, the STATUS is valid only TEXT DISK STATUS following OPENs and CLOSEs. OPEN CLOSE The TEXT clause specifies that the file is a byte-oriented TEXT (character-oriented) file. The TEXT clause only has effect on TEXT DISK files, since files assigned to any other device are DISK automatically assumed to be TEXT files. Any TEXT file must have TEXT TEXT a RECORD of length 1 (a BYTE variable). RECORD BYTE The TTY clause is equivalent to the CON clause. TTY CON The VALUE clause may be used to give the file an external VALUE name. The file is always referenced by the program by the internal name (id-1). The external name is the name which will be recorded in the disk directory for DISK files, and has no DISK effect for files assigned to other devices. If the VALUE clause VALUE is omitted, the external file-name is derived from the internal file-name: declaring a file named 'test.file' with no VALUE VALUE clause is equivalent to having a 'VALUE "TEST.FIL"' clause. The VALUE VALUE clause is overridden by the FILE1 and FILE2 clauses on the VALUE FILE1 FILE2 first OPEN of the file. After that, only the 'VALUE str-3' OPEN VALUE clause will change the name of the file. The 'VALUE lit-3' VALUE clause takes effect only if FILE1 and FILE2 were not specified FILE1 FILE2 for the file. The VALUE clause may be used to set defaults for VALUE the FILE1 and FILE2 clauses. For example, if a file is declared FILE1 FILE2 with 'FILE1, value "B:TEST.FIL"' and the file-name entered on the command-line is 'WORK', the actual (effective) external name of the file will be "B:WORK.FIL". OPENs and CLOSEs only have effect on files assigned to DISK, OPEN CLOSE DISK and are ignored for files assigned to other devices. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:51 FILE declaration FILE declaration EXAMPLES ________ (standard sector-oriented disk file) : : field disk.buff 128; {This could be replaced by a } {RECORD declaration with multiple } { sub-fields. } file account.data, disk, random, key acct.file.key, record disk.buff, status acct.cpm.stat, value "ACCT.DAT"; : : (standard disk text file) : : string text.file.name 13 value "WORK.TXT"; string disk.buff 1024; byte disk.char; file text.file, disk, text, record disk.char, buffer disk.buff, value text.file.name; : : PARASOL language manual Copyright (C) 1982, Para-Soft Pg:52 FIND statement FIND statement FIND {NEXT } GIVING bin-2 [ADDRESS word-3] ____ ____ ______ _______ FIND NEXT GIVING ADDRESS ____ ____ ______ _______ {str-1 } (lit-1 } {file-1} This statement implements the CP/M find-file, and find-next functions. The bin-2 variable gets the status value returned by CP/M. If the ADDRESS clause is used, the word-3 variable gets ADDRESS the address in the default disk buffer of the disk-directory entry. The NEXT clause should only be used in a statement following NEXT a FIND statement, with no intervening disk-related statements FIND executed. See the CP/M documentation on the find-file and fine- next-file functions for further information. If str-1 or lit-1 is used, the value is formatted into the CP/M default-fcb at location ^h5c prior to making the system call. If file-1 is used, the fcb of the referenced file is used. If bin-2 gets a value of 0, 1, 2, or 3, the file was found. If bin-2 gets a value of ^hff, the file was not found. No other status values are defined for these functions. EXAMPLES ________ : : byte find.result; pointer to string find.ptr; string file.name 13 value "WORK.TXT"; : : find file.name giving find.result address find.ptr; if find.result <> ^hff then display "the file was found"; fi; : : {---a routine to display the directory---} find "*.*" giving find.result address find.ptr; while find.result <> ^hff do add 1 to find.ptr; {skip drive-byte} move @find.ptr to file.name length 11; nove 0 to file.name[+11,byte]; display file.name; find next giving find.result address find.ptr; od; : : PARASOL language manual Copyright (C) 1982, Para-Soft Pg:53 GOTO statement GOTO statement {GOTO {id-1 } ____ GOTO ____ {GO TO} {END } __ ___ GO TO END __ ___ {@word-id} This statement causes a transfer of program control to another place. If the END option is used, control passes to the final END _____ END END statement of the program (program execution terminates). If the '@word-id' option is used, program control transfers to the address contained in 'word-id'. If the 'id-1' option is used, 'id-1' may reference either a program-label (the normal usage), or a variable name in which case the byte-values at that address and subsequent addresses are executed by the processor; caution should be exercised with this option. 'id-1' may reference a label which is declared in the program following the GOTO statement in which it is used. GOTO 'id-1' may NOT reference a SEGMENTED procedure-name. SEGMENTED Although it MAY reference a non-segmented procedure-name, this usage is not recommended. EXAMPLES ________ : : loop.the.hard.way: If switch.1 < 5 then goto end.this.loop; fi; : : add 1 to switch.5; goto loop.the.hard.way; end.this.loop: if switch.5 > 5 then display "error in manual loop"; goto end; fi; : : PARASOL language manual Copyright (C) 1982, Para-Soft Pg:54 IF statement IF statement IF cond-1 [THEN stmt-list-1] [ELSE stmt-list-2] FI __ ____ __ IF THEN ELSE FI __ ____ __ This statement provides conditional execution of statements depending upon the 'truth' of an evaluated logical condition. The THEN is optional, as is the entire THEN clause. If the THEN THEN THEN clause is omitted, usually the ELSE clause will be included THEN ELSE resulting in an IF statement which executes a statement-list when IF a condition is false. Either statement-list may contain the EXITIF statement. If EXITIF both the THEN and ELSE clauses are present, the THEN clause is THEN ELSE THEN followed by an implicit EXITIF statement. EXITIF EXAMPLES ________ : : if condition.flag = test.flag then display "1st line of true part"; display "2nd line of true part"; else display "1st line of false part"; display "2nd line of false part"; fi; : : if counter = 5 else display "this is shown if counter <> 5"; fi; : : PARASOL language manual Copyright (C) 1982, Para-Soft Pg:55 INPUT statement INPUT statement INPUT byte-1 FROM {num-1 } _____ INPUT FROM _____ {byte-2} This statement provides access to the microprocessor input ports. See the OUTPUT statement for access to the output ports. OUTPUT The (num-1/byte-2) specifies the port number to input from. The byte-1 specifies the variable which is to receive the value. If byte-2 is specified, the resultant code is self- modifying, and the compiler will print a warning that the code is not ROM-able. EXAMPLES ________ : : set in.port = 0; set out.port = 1; byte var.in.port; byte var.out.port; : byte input.data; byte output.data; : : input input.data from in.port; input input.data from var.in.port; output output.data to out.port; output output.data to var.out.port; : do input input.data from in.port; od until in.port and ^h40; {example of status-wait} : : PARASOL language manual Copyright (C) 1982, Para-Soft Pg:56 JUSTIFY statement JUSTIFY statement JUSTIFY str-1 {LEFT } [LENGTH {cnst-1}] _______ ______ JUSTIFY LEFT LENGTH _______ ______ {RIGHT} {bin-1} _____ RIGHT _____ This statement justifies str-1 to the left or right of a given field-width. If str-1 is justified LEFT, any leading space characters are LEFT deleted, then trailing space characters are added to fill out LENGTH bytes. LENGTH If str-1 is justified RIGHT, any trailing space characters RIGHT are deleted, then leading space characters are added to fill out LENGTH bytes. LENGTH If LENGTH is not specified, the length used is the declared LENGTH length of str-1 minus 1 (to allow room for the string- terminator). If LENGTH is specified, the resulting string will LENGTH occupy LENGTH + 1 bytes (including the string terminator). LENGTH Note that moving a TRSING which has no leading space TRSING characters to a FIELD of greater length does a justify-left FIELD operation except that no string-terminator byte is stored. If str-1 already has a length greater than or equal to LENGTH, it is not changed. This statement will not truncate str- ____ _________ ____ ___ ________ ____ LENGTH 1, except for removal of leading or trailing space characters. __ ______ ___ _______ __ _______ __ ________ _____ ___________ EXAMPLES ________ : : string output.string 31; string work.string 25; word work.value.1, work.value.2; : : convert work.value.1 to dec work.string; justify work.string right length 15; move work.string to output.string length 15; convert work.value.2 to dec work.string; justify work.string right length 15; move work.string to output.string length 15; display output.string; : : PARASOL language manual Copyright (C) 1982, Para-Soft Pg:57 MCALL statement MCALL statement MCALL {cnst-1} _____ MCALL _____ {label} [USING [x1 [,x2 [,x3 [,x4]]]]] _____ USING _____ [GIVING [y1 [,y2 [,y3 [,y4]]]]] ______ GIVING ______ x1, x2, and x3 may be a constant, or a binary variable (8 or 16-bit). x4 may be a constant or an 8-bit variable. y1, y2, and y3 should be WORD variables. y4 should be a WORD BYTE variable. BYTE This statement provides access to machine-language routines. The address of the routine is specified by (cnst-1/label). The microprocessor registers may be pre-loaded with values prior to the machine CALL instruction by specifying the USING clause. The USING values of the microprocessor registers following return from the call may be stored in variables by specifying the GIVING clause. GIVING If the USING clause is specified, the registers are loaded USING as follows: x1 goes into register-pair BC x2 goes into register-pair DE x3 goes into register-pair HL x4 goes into the A register If the GIVING clause is specified, the register values are GIVING stored as follows: y1 gets the value of the register-pair HL y2 gets the value of the register-pair DE y3 gets the value of the register-paid BC y4 gets the value of the A register Any of the items (x1,x2...y3,y4) may be omitted, but the commas preceding them are required to indicate the vacant position(s). There is no provision in PARASOL for checking that the address called is valid. The programmer is responsible for insuring that the expected routine is present at the address specified. The microprossor carry (C) and zero (Z) flags may be tested following the MCALL statement, if desired. See the section on MCALL conditional expressions. See the EXTERNAL statement for examples of MCALL ___ ___ ________ _________ ___ ________ __ _____ EXTERNAL MCALL ________ _____ PARASOL language manual Copyright (C) 1982, Para-Soft Pg:58 MOVE statement MOVE statement MOVE {var-1 } TO var-2 [LENGTH cnst-1] ____ __ ______ MOVE TO LENGTH ____ __ ______ {cnst-1} {lit-1 } This statement copies data from one variable into another. The variables must be of compatible types. The table below lists the possible combinations. CONSTANT MOVES cnst-1 (numeric constant) may be moved to: BYTE , BYTE POINTER, WORD, WORD-POINTER BCD, and BCD-POINTER BIT is allowed if cnst-1 is either 0 or 1. lit-1 (string constant) may be moved to: STRING and STRING-POINTER VARIABLE MOVES Type of var-1 Allowable types for var-2 ------------- -------------------------- BIT none BYTE or BP BYTE, BP, WORD, WP WORD or WP BYTE, BP, WORD, WP BCD or BCDP BCD or BCD-POINTER STRING STRING, SP, or FIELD FIELD STRING, SP, or FIELD RECORD RECORD The LENGTH clause is valid only when moving STRING LENGTH variables. If an 8-bit value is moved to a 16-bit variable, the value will have a high-order byte of zero. If a 16-bit value is moved to an 8-bit value, the hi-order byte is discarded, and a truncation warning is printed on the compiler listing. When moving RECORDs, the length actually moved is the shorter of the lengths of the two records. If the destination RECORD is the shorter, a truncation warning will be listed. STRING and FIELD MOVES MOVE str-1 TO str-2; This will move the current contents of str-1 to str-2. There is NO provision to check that the resulting value will fit within the declared length of str-2. The string is moved byte-by-byte until a null terminator is encountered. MOVE str-1 TO str-2 LENGTH cnst-1; This will move (cnst-1) number of bytes from str-1 to str-2. That number of bytes is always moved regardless of either the declared lengths or the current dynamic lengths PARASOL language manual Copyright (C) 1982, Para-Soft Pg:59 MOVE statement MOVE statement of either string. MOVE str-1 TO field-2; This will move the lesser of: (1) the current dynamic length of str-1, or (2) the declared length of field-2. If the dynamic length of str-1 is greater than the declared length of field-2, str-1 will be truncated to fit into field-2. If str-1 is shorter than field-2, extra space characters will be appended to fill out the declared length of field-2. MOVE field-1 TO field-2; This will move the lesser of the lengths of the two fields. If the destination field is longer than the source field, it will be padded with spaces to fill out its length. If the destination field is shorter than the source field, the value will be truncated to fit into the destination field. MOVE field-1 TO str-2; This will move the declared length of field-1, followed by a null terminator byte. There is NO provision to check that the value will fit within the declared length of str-2. MOVE rec-1 TO rec-2; This will move the lesser of the lengths of the two records. If the destination record is longer than the source record, the values in the record past the length of the source record are undisturbed. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:60 MULTIPLY statement MULTIPLY statement MULTIPLY {num-1 } BY {num-2 } [GIVING num-3] ________ ______ MULTIPLY BY GIVING ________ ______ {cnst-1} {cnst-2} This statement will multiply the two given values together. If the GIVING clause is specified, the result is stored in num-3. If the GIVING clause is not specified, the result is stored in num-1, and cnst-1 may not be used. If both cnst-1 and cnst-2 are specified, the multiplication is done at compile-time, and the statement is optimised to a MOVE statement. All variables must be of compatible types. If any variable is BCD, all must be BCD. Binary multiplication is performed modulus 65536. If any value is a BYTE value, it is treated as a WORD with a high-order byte of zero. The multiplication is always done as a 16-bit multiply. If the destination is a BYTE field, a truncation warning will be printed. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:61 NULL statement NULL statement NULL ____ NULL ____ This statement generates no code of itself. It is used merely as a place-holder in situations where a statement is required, or where some statement is desired for readibility. It is most useful in the SWITCH statement to select values which SWITCH need no action when there is some error action to be done in the ELSE clause of the SWITCH statement. EXAMPLES ________ : procedure debugging.routine: null; : : switch on wk.byte: 0 - 15: null; {- fall thru if in this range -} else begin display "That cannot be greater than 15"; goto get.operator.input; end; endswitch; : : if wk.byte = 5 then { In this case, the THEN clause } null; { could be omitted, but the } else { use of the NULL statement } add 3 to wk.byte; { helps the readability. } fi; PARASOL language manual Copyright (C) 1982, Para-Soft Pg:62 OPEN statement OPEN statement OPEN file-1 ____ OPEN ____ [ INPUT ] [ OUTPUT ] [ IO ][ OI ] _____ ______ __ __ INPUT OUTPUT IO OI _____ ______ __ __ [ [ NO ] REMOVE ] __ ______ NO REMOVE __ ______ [ SHARED ] ______ SHARED ______ [ ERROR { STANDARD } ] _____ ________ ERROR STANDARD _____ ________ { statement } This statement opens a file for accessing. If the file is not a disk file, the OPEN statement performs no action, and is entirely optional. If INPUT is specified, the file may be read-from. If OUTPUT is specified, the file may be written-to. If both INPUT and OUTPUT are specified, the file may be either read or written. IO and OI also allow both reading from and writing to the file. If none of these options are specified, the file may be written-to or read-from. The REMOVE clause specifies that a new file is being created, and that any existing file of the same name should be deleted (removed) from the disk directory. If OUTPUT or OI is specified, REMOVE is assumed. The NO REMOVE clause is provided to override this deletion of existing files. If NO REMOVE is specified, the existing file will be accessed, and no new file will be created. The SHARED clause specifies that the file may be accessed under the MP/M shared-file protocol. This allows several programs to access the same file at the same time. If the LOCK or UNLOCK options are used with READ or WRITE statements, they will be ignored unless both of the following conditions are met: (1) The program must be running under MP/M, and (2) The file must have been OPENed with the SHARED clause. The ERROR clause provides the ability to take action if any errors occur during the OPEN process. Except under unusual conditions (such as a full directory on the disk), the only error likely to happen is a file not found. If you want to be certain of the cause of the error, define a STATUS variable for the file, and test it inside the ERROR statement. Refer to the CP/M documentation for information about the error codes returned by CP/M. ERROR STANDARD tells the compiler to take the standard error recovery action on an error during the OPEN process. This action is to print a run-time message "FILE OPEN ERROR" and terminate the program. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:63 OUTPUT statement OUTPUT statement OUTPUT {byte-1} TO {byte-2} ______ OUTPUT TO ______ {cnst-1} {cnst-2} This statement provides access to the microprocessor I/O ports. The value of byte-1/cnst-1 is output to the port whose number is byte-2/cnst-2. If byte-2 is used, the generated code is self-modifying, and a warning message that the code is non- ROMMABLE is printed on the compiler listing. See the INPUT statement for examples. INPUT PARASOL language manual Copyright (C) 1982, Para-Soft Pg:64 POINTER statement POINTER statement POINTER TO {BYTE } id-1 [ VALUE {cnst-1} ] _______ ____ _____ POINTER TO BYTE VALUE _______ ____ _____ {WORD } {HIMEM } ____ _____ WORD HIMEM ____ _____ {STRING} ______ STRING ______ {BCD } ___ BCD ___ Note: this statement may also take the following forms: {BYTE } POINTER id-1 [ VALUE cnst-1 ] ____ _______ _____ BYTE POINTER VALUE ____ _______ _____ {WORD } ____ WORD ____ {STRING} ______ STRING ______ {BCD } ___ BCD ___ This statement defines a storage area for a special-purpose WORD variable which is to be used as a pointer. When this WORD variable is referenced normally (with no "@" in front of it), it is treated in all respects as a WORD variable. But when id-1 is WORD preceded by "@" ( @id-1 ), it takes on the variable-type of what it points-to. A BYTE POINTER will be treated as a BYTE, and a STRING POINTER will be treated as a string. The variable may have a value pre-assigned to it with the VALUE clause. The key-word HIMEM indicates that the value stored HIMEM here should be the address of the first byte following the last- used memory location of the program. This is useful for user- allocated data storage of arrays, tables, etc. EXAMPLES ________ : : byte pointer wk.bp; word pointer wk.wp; byte pointer master.himem value himem; external word himem.limit address 6; : : move master.himem to wk.bp; { a normal WORD to WORD move } {-- initialize all memory above the program --} while wk.bp < himem.limit do { a WORD to WORD compare } move 0 to @wk.bp; { move 0 to a BYTE } add 1 to wk.bp; { point to the next location } od; : : PARASOL language manual Copyright (C) 1982, Para-Soft Pg:65 POINTER statement POINTER statement Note that when incrementing a pointer (with the ADD statement), that the value should be incremented by 1 for a byte- pointer, and by 2 for a word-pointer. When incrementing a string-pointer, it may be incremented by the defined length of the string, but this will waste space. The most compact storage is realised by incrementing by the dynamic length of the string plus one (for the null terminator). The example below gives a very efficient method of correctly incrementing a string-pointer. : : string wk.str 32; string pointer wk.sp value himem; : : do accept "Enter the next string: ",wk.str; if wk.str = "" then exitdo; fi; move wk.str to @wk.sp; size @wk.sp giving address wk.sp; { gives addr of null } add 1 to wk.sp; { skip the null } od; PARASOL language manual Copyright (C) 1982, Para-Soft Pg:66 POP and PUSH statements POP and PUSH statements POP word-1 ___ POP ___ This statement performs a machine POP instruction. The results of the POP are stored in word-1. This statement uses the same machine stack as the CALL and EXIT statements use. This statement is provided for use by programmers who are familiar with the mechanism involved in subroutine linkage and stack manipulation. It is not intended for general purpose usage, and its use should be avoided whenever possible. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:67 PRINT directive PRINT directive PRINT ON _____ __ PRINT ON _____ __ PRINT OFF _____ ___ PRINT OFF _____ ___ PRINT PAGE _____ ____ PRINT PAGE _____ ____ This is a compiler directive. It has no effect on the generated object code. PRINT PAGE causes the compiler listing to skip to the top of the next page. PRINT OFF turns off the compiler listing. This is useful when compiling a program containing libraries which are known to work correctly. The library could begin with a PRINT OFF directive, and end with a PRINT ON directive. This would omit the listing of the library in the compiler listing. Note: If the PRINT FULL compiler switch was used, PRINT OFF has no effect. PRINT ON turns the compiler listing back on following a PRINT OFF. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:68 PROCEDURE statement PROCEDURE statement PROCEDURE id-1 : statement-1 _________ _ ___________ PROCEDURE : _________ _ This statement defines a procedure which is not executed in- line, but is called from the main program. id-1 is the name of the procedure. The procedure is invoked with a statement of the form: CALL id-1; The colon following id-1 is required. In practice, statement-1 will generally be a BEGIN-END block, which may, or may not, have local data and procedure declarations of its own. See also the SEGMENTED statement. SEGMENTED PARASOL language manual Copyright (C) 1982, Para-Soft Pg:69 READ statement READ statement READ file-1 [ FRESH ] [ LOCK ] ____ _____ ____ READ FRESH LOCK ____ _____ ____ [ ERROR { STANDARD } ] _____ ________ ERROR STANDARD _____ ________ { stmt-1 } This statement causes the record defined for file-1 to be read from the file. The FRESH clause forces a fresh I/O operation to be performed. With BLOCKED-record files, a sector-buffer is kept in memory from any previous I/O operation on that file. If FRESH is not specified, a record will be retrieved from the sector-buffer if it (or part of it) is present in memory. FRESH causes the sector-buffer to be discarded, and a fresh copy obtained from disk. This only has an effect if you are running a multi-user application ( and the file was OPENed SHARED ), since the sector on disk may have been updated by another user since having been read by you. The other user may not have even accessed the same record-number as you, but merely one adjacent to the one you are accessing. With BLOCKED files, a sector on disk may contain portions of more than one record. If file-1 is declared with NO BUFFER, then FRESH is (in NO BUFFER FRESH effect) assumed. If LOCK is specified, FRESH is assumed. LOCK FRESH The LOCK clause causes any sector(s) containing any portion of the record being read to be locked. This only has an effect if the following conditions are met: (1) The program is running under MP/M (or some other multi-user operating system which supports the same calls, such as TurboDos, or n/Star) (2) The program was compiled with the MPM compiler switch. MPM (3) The file referenced by the READ statement was OPENed in READ SHARED mode. The ERROR clause provides a course of action to be taken if ERROR any error occurred during the READ operation. if ERROR STANDARD ERROR STANDARD is specified, the default action is taken: a run-time message "FILE READ ERROR" is displayed, and the program is terminated. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:70 REBOOT statement REBOOT statement REBOOT ______ REBOOT ______ This statement terminates program execution and re-loads CP/M into memory. The normal method of program termination is to "fall-thru" the end of the program. This statement is a carry- over from an earlier version of PARASOL, and should generally be replaced with "GOTO END". PARASOL language manual Copyright (C) 1982, Para-Soft Pg:71 RECORD declaration RECORD declaration RECORD id-1; ______ RECORD ______ < data declarations > ENDREC ______ ENDREC ______ This statement provides a method of grouping related data- items together to allow them to be treated as a unit. A RECORD RECORD declaration may contain other RECORD declarations subordinate to RECORD it. Each RECORD declaration is terminated by a matching ENDREC RECORD ENDREC declaration. The length of a RECORD is the sum of all elementary items RECORD enclosed between the RECORD declaration and the ENDREC RECORD ENDREC declaration. EXAMPLES ________ record member.rec; record member.name; field member.first.name 10; field member.middle.name 10; field member.last.name 10; endrec; field member.address 20; field member.city 10; field member.state 2; field member.zip 10; endrec; Note that a RECORD may itself contain another RECORD. RECORD RECORD PARASOL language manual Copyright (C) 1982, Para-Soft Pg:72 REDEFINE directive REDEFINE directive REDEFINE id-1 ________ REDEFINE ________ < statement-list > ENDREDEF ________ ENDREDEF ________ This statement provides a method of defining an area of storage with alternate names. id-1 is a previously-defined identifier. It may be any type of identifier, but generally will be a variable-name. statement-list may be any statements, but generally will be data declarations. The data areas within the REDEFINE-ing area may, if desired, REDEFINE contain VALUE clauses, and these clauses will override any VALUE previous VALUEs originally defined. VALUE If the REDEFINE occurs within a SEGMENTED procedure, and REDEFINE SEGMENTED redefines data outside of that procedure (in global memory), then the VALUE clause is not allowed within the scope of the REDEFINE, VALUE REDEFINE and will cause a compile-time error. EXAMPLES ________ : : field disk.rec 128; redefine disk.rec; record disk.directory.rec; byte dir.user.code; field dir.name 8; field dir.ext 3; byte dir.extent; string 19; endrec; endredef; : : PARASOL language manual Copyright (C) 1982, Para-Soft Pg:73 REMOVE statement REMOVE statement REMOVE {str-1 } [ GIVING byte-1 ] ______ ______ REMOVE GIVING ______ ______ {file-1} This statement removes a file from the disk directory. If str-1 is used, it should be the ASCII name of a file. It may be preceded by a drive letter and a colon if desired. One restriction about using the file-1 option: If the file has a VALUE statement referencing a string variable, the string VALUE variable is not formatted into the FCB until the file is OPENed. OPEN If the file has never been OPENed, the filename inside the FCB OPEN will be undefined, and this statement's action will also be undefined. In general, this option should be avoided, and the str-1 option should be used. If the file has a "VALUE string" VALUE statement, you should use "REMOVE string", referencing the same REMOVE string variable. The GIVING option provides a method of testing the result of GIVING the REMOVE statement. byte-1 will get a value of 255 if the REMOVE REMOVE was unsuccessful, and a value of 0, 1, 2, or 3 if the REMOVE REMOVE was successful. REMOVE EXAMPLES ________ : : remove "TEST.FIL" giving wk.byte; if wk.byte = ^hff then display "File was not removed"; else display "File has been removed"; fi; PARASOL language manual Copyright (C) 1982, Para-Soft Pg:74 RENAME statement RENAME statement RENAME {str-1 } TO {str-2 } [ GIVING byte-1 ] ______ ______ RENAME TO GIVING ______ ______ {file-1} {file-2} This statement allows you to rename a file on disk to a new name. str-1/file-1 references the existing name of the file. str-2/file-2 references the name you want the file to become. str-1 and str-2 should be the ASCII name of the file. Either may be preceded by a drive letter and a colon, but it will be ignored if it is present in str-2. A RENAME will operate only RENAME on one drive. There are some restrictions to using the file-1 or file-2 options. See the REMOVE statement for a description of these REMOVE restrictions. In general, it is best to use the str-1/str-2 options. The GIVING clause provides a method of testing the results GIVING of the RENAME statement. byte-1 will contain 255 if the RENAME RENAME RENAME was not successful, and 0, 1, 2, or 3 if the RENAME was RENAME sucessful. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:75 SCAN statement SCAN statement SCAN str-1 FOR [ ANY ] {str-2} ____ ___ ___ SCAN FOR ANY ____ ___ ___ [ NO ] {lit-2} __ NO __ [ TRAILING ] ________ TRAILING ________ [ GIVING bin-1 [ ADDRESS bin-2 ] ] ______ _______ GIVING ADDRESS ______ _______ [ TRUE stmt-1 ] ____ TRUE ____ [ FALSE stmt-2 ] _____ FALSE _____ This statement has four different actions depending on the options chosen: SCAN ANY will search through str-1 for ANY chararcter SCAN ANY which matches ANY character in str-2. SCAN NO will search through str-1 for ANY character SCAN NO which does NOT match ANY character of str-2. SCAN TRAILING will search through str-1 for ANY SCAN TRAILING trailing characters which match ANY character in str-2. SCAN alone (with none of the ANY, NO, or TRAILING SCAN ANY NO TRAILING options selected) will scan through str-1 for a sequence of characters which exactly matches the entire contents of the str-2 string. The string must match in the same order. The GIVING clause provides two different outputs from the GIVING SCAN statement: SCAN bin-1 provides a character-count of the number of characters passed over before the SCAN was satisfied. If SCAN the SCAN was NOT satisfied, bin-1 gets a value equal to the SCAN number of characters in str-1. bin-2 provides the address of the location where the SCAN was satisfied. If the SCAN was NOT satisfied, bin-2 SCAN SCAN gets the address of the null terminator byte in str-1. If the TRUE clause is present, stmt-1 is executed if the TRUE SCAN WAS satisfied. SCAN If the FALSE clause is present, stmt-2 is executed if the FALSE SCAN was NOT satisfied. SCAN PARASOL language manual Copyright (C) 1982, Para-Soft Pg:76 SCAN statement SCAN statement EXAMPLES ________ : : byte wk.byte; byte pointer wk.bp; string wk.str 50 value "this is an example "; string digits 11 value "0123456789"; : : scan wk.str for "is" giving wk.byte; {-- wk.byte will get a value of 2. "th" was skipped-over -} : : scan wk.str for any "xyz" giving wk.byte; {-- wk.byte will get 12. "this is an e" was skipped --} : : scan wk.str for trailing " " giving address wk.bp; move 0 to @wk.bp; {-- this shows an example of removing trailing spaces {-- from a string. wk.bp gets the address of the first {-- space following "example". Moving a zero to this {-- byte terminates the string at this location. : : get.a.number: accept "Enter a number: ",wk.str; scan wk.str for no digits error begin display "That had some non-numeric characters in it" goto get.a.number; end; PARASOL language manual Copyright (C) 1982, Para-Soft Pg:77 SEGMENTED directive SEGMENTED directive SEGMENTED procedure-definition _________ SEGMENTED _________ "SEGMENTED" MUST BE IMMEDIATELY FOLLOWED BY "PROCEDURE". This statement provides overlay capability. You can write a program which is actually larger than 64K by using overlays. If the source program contains ANY SEGMENTED procedures, an overlay SEGMENTED file (.OVL) will be generated with the same name as the .COM file. The .COM and .OVL files are a matched set. Do not attempt to run one without the other, or with a different version from the other. It will give unpredictable results. (Actually, a system crash is a pretty good prediction.) In order to obtain any benefit from overlays, you need at least two in a row. The compiler has the capability of defining as many overlay levels as you need. In order for two overlays to occupy the same memory area, they MUST be defined contiguously in the source program. If you want to begin a new overlay area, you MUST have some (non-comment) statement between the preceding SEGMENTED declaration and the following SEGMENTED declaration. SEGMENTED SEGMENTED You may have as many different overlays occupying the same memory area as desired (within the CP/M file-size constraints). The run-time overlay manager will keep track of which overlay is in memory in each overlay area. If a segmented procedure is called which is already resident, it is immediately invoked. It will be read from disk only when it is not resident. NOTE that variable definitions within the body of the procedure having a VALUE clause will be re-initialized whenever the overlay is loaded from disk, but WILL NOT be re-initialized if the overlay is already resident. A segmented-procedure has the same scope rules as any other procedure, with the following exceptions: 1. A SEGMENTED procedure cannot be forward-referenced. SEGMENTED The procedure MUST be appear in the source code prior to any call-reference to it. 2. You cannot CALL a SEGMENTED procedure from another SEGMENTED procedure which occupies the same memory area 3. Data definitions within the segmented procedure which use the VALUE clause will only be re-initialized when the overlay is freshly read from disk. 4. Data definitions within the segmented procedure may REDEFINE data in global memory, but MAY NOT have REDEFINE any VALUE clauses within the scope of the REDEFINE VALUE REDEFINE statement. VALUE clauses are OK if the data being VALUE redefined is in the same overlay. The compiler automatically keeps track of the sizes of the various overlays in each given area, and will reserve an area sufficient to accommodate the largest overlay. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:78 SEGMENTED directive SEGMENTED directive EXAMPLES ________ byte global.byte; segmented procedure A.1: begin display "inside A.1"; end; segmented procedure A.2: begin { A.1 and A.2 both will occupy the display "inside A.2"; { same memory area call A.1; { This will cause an error message { A.2 wouldn't be here to return-to. end; procedure global.1: begin { this terminates the first display "inside global.1"; { overlay area since it's end; { not SEGMENTED segmented procedure B.1: begin byte B.1.byte value 0; display "inside B.1"; { A new overlay add 1 to B.1.byte; end; segmented procedure B.2: begin { B.1 and B.2 will occupy display "inside B.2"; { the same memory area add 1 to global.byte; call A.2; { This is OK, since A.2 is { not in the same memory area end; {---main program---} call B.1; { B.1.byte is incremented to 1 call B.1; { B.1.byte is incremented to 2 { since B.1 is still resident, it is { not reloaded from disk. call B.2; { B.1 overlay is discarded call B.1; { B.1.byte is reloaded to zero and { incremented to 1. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:79 SET directive SET directive SET id-1 {TO} {cnst-1 } ___ SET TO ___ {= } {key-word-1} = This statement provides two capabilities. 1. The primary usage is to give a name to constants used in the program. When cnst-1 is used, id-1 takes on the value of cnst-1. Wherever id-1 is used in the program, it is replaced with a constant of the value cnst-1. 2. Another use is to define synonyms for key-words. One usage would be in tables being built in the data-declaration section of the program, to shorten the keywords to make the tabular structure more apparant. (See the example below). Another capability is to implement conditional compiling of source code depending on the SETtings of SET different constants. For this type of usage, the key-word-1 should be either COMMENT or NULL. NULL is a special case in COMMENT NULL NULL this context, and will be ignored by the compiler, while COMMENT will cause a line of code to be omitted. COMMENT EXAMPLES ________ set debug = null; {-- this enables debugging code. To disable debugging {-- code, type "set debug = comment;" : : debug if wk.byte > 5 then debug display "Value out of valid range"; debug fi; {-- the above three lines of code will be compiled into {-- the source if debug is SET to NULL. They SET NULL {-- will be ignored by the compiler if debug is set to {-- COMMENT. COMMENT : : set b = byte; set w = word; set v = value; : : b v 1; w v "AA"; b v 2; w v "BB"; {--This is equivalent to: {-- byte value 1; word value "AA"; {-- byte value 2; word value "BB"; PARASOL language manual Copyright (C) 1982, Para-Soft Pg:80 SIZE statement SIZE statement SIZE {string-1} GIVING [ bin-1 ] [ ADDRESS bin-2 ] ____ ______ _______ SIZE GIVING ADDRESS ____ ______ _______ {field-1 } {record-1} This statement determines the size of a variable, returns the number of bytes in the variable, and optionally returns the address following the last-used byte of that variable. If field-1 or record-1 is used, the SIZE returns a constant SIZE value of the declared size of the variable. The compiler will optimise this to a MOVE statement. It is recommended that you MOVE use the "##" construct for fixed-length variables. When string-1 is used, the dynamic length of the string is determined. bin-1 will get a value equal to the number of characters in the string prior to the terminator byte. bin-2 will get the address of the null terminator byte. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:81 STRING variable declaration STRING variable declaration STRING [ id-1 ] [LENGTH] length-1 [ VALUE lit-1 ] ______ STRING LENGTH VALUE ______ ,[ id-2 ] [LENGTH] length-2 [ VALUE lit-2 ] ... LENGTH VALUE This statement defines a STRING variable. STRING id-1 is the name by which the variable is to be referenced. The key-word LENGTH is optional, but the value length-1 is LENGTH NOT optional. This is a constant which defines the maximum size of the string. This determines the number of bytes allocated to contain the string. If you want to store a string up to 5 characters in length, for example, you should use a length of at least 6 to allow room for the terminator byte. The VALUE clause specifies a value to be assigned to id-1 at VALUE compile-time. Note that there are very few automatic checks in PARASOL against extending a STRING past the number of bytes allocated for STRING it. It is entirely your responsibility to insure that enough space has been allocated for a string, and to insure that no operations result in exceeding that allocation. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:82 SUBTRACT statement SUBTRACT statement SUBTRACT {num-1 } FROM {num-2 } [ GIVING num-3 ] ________ ______ SUBTRACT FROM GIVING ________ ______ {cnst-1} {cnst-2} This statement does an arithmetic subtraction of two values and stores the result. num-1/cnst-1 is subtracted from num- 2/cnst-2. If the GIVING clause is present, the result is stored GIVING in num-3. If no GIVING clause is present, the result is stored GIVING in num-2, and cnst-2 cannot be used. If both cnst-1 and cnst-2 are used, the GIVING clause is GIVING required, and the SUBTRACT statement is optimised by the compiler SUBTRACT to a MOVE statement. MOVE If cnst-1 is used, and equals zero, the SUBTRACT statement SUBTRACT is optimised to a MOVE statement. MOVE All variables used in this statement must be of compatible types. Either all must be binary, or all must be BCD. If ANY variable is a 16-bit variable, the subtraction is done as a 16-bit subtraction. If the result field is 8-bit, a truncation-error will be printed on the compiler listing. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:83 SWITCH statement SWITCH SWITCH ON var-1 : ______ _ SWITCH ON : ______ _ [ switch-op [ , switch-op ] ... : stmt-1 ] ... _ , : _ [ ELSE stmt-3 ] ____ ELSE ____ ENDSWITCH _________ ENDSWITCH _________ switch-op can be: 1. A constant value, in which case the SWITCH tests var-1 SWITCH to be equal to that value. 2. A range of values expressed as : cnst-1 {TO} cnst-2 __ TO __ {- } - In this case the SWITCH tests var-1 to fall within the range SWITCH of values from cnst-1 to cnst-2 (inclusive). This statement provides the most powerful decision-making capability in PARASOL. The variable begin tested, var-1, may be a BYTE, WORD, STRING, or BCD, or any POINTER type. BYTE WORD STRING BCD POINTER The text description of the operation of this statement is fairly involved. It may be helpful to look at the examples given below before reading the text. The operation of the statement should appear nearly intuitive. The SWITCH statement begins with the switch-op comparisons SWITCH in the order in which they are written. Each switch-op is evaluated in turn. The first switch-op which is true causes its associated statement to be executed. Execution resumes following the ENDSWITCH statement. The first switch-op which is ENDSWITCH true is the only one which will be true, since no other switch- ops will be evaluated after that. If no switch-op was found to be true, the ELSE statement is ELSE executed, if present. Execution resumes following the ENDSWITCH ENDSWITCH statement. EXAMPLES ________ switch on wk.byte: 0: null; {take no action if zero} 1 - 5, 8: begin display "wk.byte = 1, 2, 3, 4, 5, or 8"; end; 6,12,18,24,30,36: begin display "wk.byte is a multiple of 6"; end; else begin display "wk.byte is some other non-zero value"; end; endswitch; PARASOL language manual Copyright (C) 1982, Para-Soft Pg:84 TRACEBACK statement TRACEBACK statement traceback [ cnst-1 ] _________ traceback _________ This statement provides a run-time display of a portion of the subroutine-linkage stack. cnst-1 tells the compiler how many words of data from the stack to display. If cnst-1 is omitted, 10 is used. This statement is called internally for disk-file-related STANDARD error-handling routines. STANDARD PARASOL language manual Copyright (C) 1982, Para-Soft Pg:85 WORD data declaration WORD data declaration WORD id-1 [ VALUE cnst-1 ] ____ _____ WORD VALUE ____ _____ [, id-2 [VALUE cnst-2 ] ... _____ , VALUE _____ This statement defines storage for a 16-bit binary numeric variable. The VALUE clause provides a value assigned to that VALUE variable at compile-time. id-1 is the name by which this variable will be referenced. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:86 WRITE statement WRITE statement WRITE file-1 [ { LOCK UNLOCK } ] _____ ____ ______ WRITE LOCK UNLOCK _____ ____ ______ { UNLOCK } ______ UNLOCK ______ [ ERROR { STANDARD } _____ ________ ERROR STANDARD _____ ________ { stmt-1 } This statement copies data from a record-area and writes it to the file identified by file-1. The UNLOCK option is used when the record being written has UNLOCK been previously LOCKed by an earlier READ statement. LOCK READ The LOCK UNLOCK option is used when the record being written LOCK UNLOCK has not been previously LOCKed. This could be the case when LOCK adding a new record to the end of a file, for example. This may be needed when updating records in a BLOCKED file which is open BLOCKED in SHARED mode. Since BLOCKED records do not always begin on a SHARED BLOCKED sector boundary, another program may have an adjacent record read which happens to overlap onto part of a sector which is used by the record in your program. The LOCK UNLOCK option protects you LOCK UNLOCK from accidentally wiping out that portion of a record. The ERROR statement provides a mechanism for dealing with ERROR I/O errors occurring during the processing of the WRITE WRITE statement. If any error condition arises, the ERROR statement is ERROR executed. If ERROR STANDARD is specified, the default action is ERROR STANDARD to display a run-time error message "FILE WRITE ERROR", and terminate the program. PARASOL language manual Copyright (C) 1982, Para-Soft Pg:87 @