home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / tmtp100o.zip / MANUAL.OS2 < prev    next >
Text File  |  1997-04-02  |  35KB  |  1,102 lines
  1.                    Pascal Lite Compiler for OS/2
  2.                         [ Version 1.00 ]
  3.  
  4.                     TMT Development Corporation
  5.  
  6. Introduction
  7. ------------
  8.  
  9. The TMT Pascal Lite compiler is a fast compiler for the Pascal language.
  10. The compiler emits 32-bit code and supports many language extensions
  11. from Borland Pascal (BP), as well as more powerful extensions.
  12.  
  13. The compiler requires a floating point co-processor.
  14.  
  15. This manual consists of the following parts:
  16.  
  17.     - compiler installation and running
  18.     - configuration file
  19.     - memory organization
  20.     - calling convention
  21.     - implemented language description:
  22.          - restriction
  23.          - extensions
  24.          - incompatibilities
  25.     - units description:
  26.          - DOS
  27.          - CRT
  28.          - USE32
  29.          - ERRCODE
  30.          - DEBUG
  31.          - STRINGS
  32.          - OS2ORD
  33.          - DOSCALL
  34.          - OS2PMAPI
  35.     - troubleshooting
  36.     - run-time error codes
  37.  
  38.  
  39. Compiler installation and running
  40. ---------------------------------
  41.  
  42.    The Pascal Lite distribution is contained in the tmtplos2.zip archive.
  43.    Please, read the license.doc file before the installation.
  44.  
  45.    Follow these instructions to run the installation process.
  46.  
  47.       - create the \TMTPLOS2 directory on one of the drives (we will call
  48.         it the x: drive) using the command:
  49.             x> md TMTPLOS2
  50.  
  51.    NOTE::: DO NOT INSTALL THE DOS AND THE OS/2 VERSIONS OF THE COMPILER INTO
  52.      THE SAME DIRECTORY. Because of file name conficts, this will make one
  53.      of the versions unusable.
  54.  
  55.       - copy the tmtp100o.zip file into the TMTPLOS2 directory:
  56.  
  57.             x> copy  tmtp100o.zip x:\TMTPLOS2
  58.             x> x:
  59.             x> cd \TMTPLOS2
  60.  
  61.       - run the PKUNZIP program to decompress the tmtp100o.zip
  62.  
  63.             x:\TMTPLOS2> pkunzip -d tmtp100o
  64.  
  65.         (the switch "-d" unpacks with subdirectories)
  66.  
  67.       - modify the PATH statement in the autoexec.bat, to include the
  68.                 x:\TMTPLOS2\BIN
  69.          subdirectory, if you so desire.
  70.  
  71.          and the INCLUDE_PATH statement in x:\TMTPLOS2\BIN\TMTRC.CFG for
  72.          the desired resources.
  73.  
  74.       - goto to \TMTPLOS2\EXAMPLES\OS2\HELLO
  75.         compile the simple test program, "HELLO.PAS", and run it:
  76.  
  77.            x:\TMTPLOS2\EXAMPLES\OS2> plt hello
  78.            x:\TMTPLOS2\EXAMPLES\OS2> hello
  79.  
  80.       - read the entire manual.os2 file before using the compiler for
  81.         any "real" application development.
  82.  
  83.  
  84. Contents of the distribution
  85. ----------------------------
  86.  
  87.    documentation:
  88.  
  89.       manual.os2         - description of the PLT compiler for OS/2.
  90.       license.doc        - license agreement
  91.       readme             - this file
  92.  
  93.    executable:
  94.  
  95.      subdirectory BIN\ contains following files:
  96.  
  97.        pltos2.cfg         - compiler configuration file
  98.        plt.exe            - the PLT compiler under OS/2
  99.        tmtrc.exe          - TMT resource compiler for OS/2 *
  100.        tmtrc.msg          - TMT resource compiler message file *
  101.        tmtrc.mac          - TMT resource compiler prologue file *
  102.        tmtrc.cfg          - TMT resource compiler configuration file *
  103.  
  104.        * not in the free version.
  105.  
  106.    standard library object modules:
  107.  
  108.      subdirectory UNITS\ contains unit files with following extensions:
  109.          .FPD - for DOS version
  110.          .FPU - for OS/2 version
  111.          .FPL - for OS/2 version (for .DLL's)
  112.  
  113.       arg                - commmand line parsing unit
  114.       crt                - crt unit
  115.       debug              - post-mortem dump unit and other debugging
  116.                            functions
  117.       dos.fpd            - dos unit
  118.       doscall            - low-level DOS interface and OS/2
  119.       os2ord             - OS/2 function ordinal numbers (OS/2 version only)
  120.       os2pmapi           - OS/2 presentation manager interface (OS/2 version only)
  121.       errcodes           - run-time error codes
  122.       strings            - strings unit
  123.       system             - system unit
  124.  
  125.       also in this directory contains files:
  126.           STUB.EXE    - stub for OS/2 executables
  127.           DOS32.EXE   - DOS32 extender
  128.           STUB32.EXE  - stub for DOS32 extender
  129.           PASSTUB.EXE - PMODE-based extender
  130.  
  131.    example:
  132.  
  133.      subdirectory EXAMPLE\DOS\ contains following examples for MS DOS:
  134.  
  135.        HELLO\ - example "Hello, World" program
  136.        FLAME\ - example of direct works with I/O ports and physical
  137.                 memory
  138.        VESADEMO\ - example of import and usage VESA.OBJ file from
  139.                   DOS32 libraries.
  140.  
  141.      subdirectory EXAMPLE\OS2 contains following example for OS/2:
  142.  
  143.        HELLO\ - example "Hello, World" program
  144.        SKELETON\ - example simple presentation manager application
  145.  
  146.       subdirectory EXAMPLE\LIN_EQ contains example of multidimensional
  147.       open arrays usage
  148.  
  149.    supplemential files:
  150.        full distribution of DOS32 extender for the MS DOS
  151.        version of Pascal/Lite
  152.  
  153.  
  154.    Running the compiler:
  155.    --------------------
  156.  
  157. The compiler is invoked with the "plt" command:
  158.  
  159.   plt [switches] <main file>
  160.  
  161. where the following switches can be used:
  162.  
  163.     -m   - make modified units (default option)
  164.     -b   - build the whole program
  165.     -c   - single compilation (without linkage)
  166.  
  167.     -t<target> - define target system for compiling
  168.         <target> = DOS - for DOS executables (default under DOS)
  169.         <target> = OS2 - for OS/2 executables (default under OS2)
  170.         <target> = OS2:FS - for OS/2 full screen executables
  171.         <target> = OS2:PM - for OS/2 presentation manage executables
  172.         <target> = OS2:DLL - for OS/2 dynamic link libraries
  173.  
  174. The suite of compiled units (*.FPx) will be created in the same
  175. directory as the sources, and the executable file will be created in the
  176. current directory (if the switch -c is not used).
  177.  
  178.  
  179. Configuration file
  180. ------------------
  181.  
  182. Before a compilation the compiler reads the settings from the special file -
  183. pltos2.cfg. It searches for one at the beginning of the current directory and
  184. then, if it doesn't find one, in the starting directory.
  185.  
  186. The configuration file "pltos2.cfg" contains the compilation parameters:
  187. one command per line.  Empty line are possible.  Comment lines are started with
  188. the ';' symbol.
  189.  
  190. The following parameters can be used in the pltos2.cfg:
  191.  
  192.     toggle settings:
  193.  
  194.        w+       - turn on the puting of warning messages
  195.        r+       - turn on the range checking
  196.        q+       - turn on the overflow checking
  197.        i+       - turn on then automatic input/output result checking
  198.        t+       - typed pointers
  199.        x+       - extended syntax
  200.        v+       - strict var checking
  201.        optreg+  - turn on the register optimization
  202.        optfrm+  - turn on the stack frame optimization
  203.        opt+     - turn on all optimization (optreg+ & optfrm+)
  204.  
  205.     Default settings: w+, r+, q+, i+, t-, x+, v+, opt+.
  206.  
  207.     file path search specification:
  208.  
  209.        srcpath    <search_path> - specifies path for the source file search
  210.        objpath    <search_path> - specifies path for the object file (.FPD,
  211.                                   .FPU, .FPL) and STUBs search
  212.        objimppath <search_path> - specifies path for the OBJ import file
  213.                                   search by use of a $L directive
  214.  
  215.  
  216.        pseudo-devices SYS: and SRC: can be used in the path line:
  217.  
  218.          SYS: means the PLT compiler directory,
  219.          SRC: means the application program directory.
  220.  
  221.        defaults:  srcpath     src:;sys:
  222.                   objpath     src:;sys:
  223.                   objimppath  src:;sys:
  224.  
  225.  
  226.     buffer size specification:
  227.  
  228.        objmax <size>    - specifiies the size of the buffer for object
  229.                           modules (fpd-files). This parameter must be
  230.                           about one and a half times the size of the
  231.                           largest fpd-file from the project.
  232.  
  233.        exemax <size>    - specifies the maximum size of the executable
  234.                           module.
  235.  
  236.  
  237.        defaults:   objmax 333000
  238.                    exemax 256000
  239.  
  240.        These values are enough for ordinary work.  But if you receive
  241.        a message about overflowing of these buffers, you'll have to
  242.        increase them.
  243.  
  244.     stack size specification:
  245.  
  246.        stack <stack_size> - specifies size of the application stack
  247.        default: 32000
  248.  
  249.     start up block (stub) name specification:
  250.  
  251.        stub  <stub_name>  - specifies the STUB name for the linker.
  252.                             default: STUB.EXE for OS/2 targeted compilation
  253.                             and DOS32.EXE for DOS targeted compilation
  254. +++0.30
  255.                             use the OBJPATH option to specify the seacrh path
  256.                             for the stub files
  257. ---0.30
  258.  
  259.     Symbol definition:
  260.  
  261.        def <symbol name>
  262.  
  263. +++0.30
  264.            The following symbols are predefined:
  265.                 __TMT__ :    always
  266.                 __DOS__ :    for DOS target
  267.             *   __OS2__ :    for all OS/2 targets
  268.             *   __DLL__ :    for .DLL targets
  269.             *   __PM__  :    for OS/2 Presentation manager targets
  270.             *   __FS__  :    for OS/2 Full screen targets
  271.             *           --   OS/2-hosted compiler only
  272. ---0.30
  273.  
  274.     error message format specification:
  275.  
  276.  
  277.  
  278.        errmw+ - specifies the MetaWare Pascal format of the error message:
  279.  
  280.                    E "HELLO.PAS" L4/C16: type mismatch
  281.  
  282.  
  283.        errmw- - specifies the BP-like format of the error message:
  284.  
  285.                    textcolor (lightred+'a');
  286.                               
  287.                    Error: HELLO.PAS (line 4, col 16): type mismatch
  288.  
  289.        This parameter allows use of the MultiEdit program as a shell
  290.        when the errmw+ parameter is set.
  291.  
  292.        The default is:  errmw-
  293.  
  294.      output of the Dos32 logo specification:
  295.  
  296.        logo+  -  enables output of the Dos32 logo during the running of
  297.                  the emitted program.
  298.        logo-  -  disables output of the Dos32 logo during the running of
  299.                  the emitted program.
  300.  
  301.        The default is: logo+
  302.  
  303. Memory organization under DOS32 extender
  304. ----------------------------------------
  305.  
  306. The PLT compiler uses the Dos32 extender for a protected-mode program.
  307. The full distributive of Dos32 is in the DOS32 subdirectory.
  308. This distributive contains all information about program execution
  309. under the 32-bit mode.  Here some important issues are presented.
  310.  
  311. The segment registers are not used in the protected mode.  Instead all
  312. address space is separated on 4Kb pages starting from the zero address.
  313. Every page has a physical equivalent in the special table (the physical
  314. address might not be equal to the logical address).  In such a case the
  315. logical address 0 corresponds to the beginning of the program code.
  316. Therefore if you try to access the physical address (video memory and so
  317. on), you will not succeed.
  318.  
  319. Nevertheless, access to the physical addresses is possible, because
  320. the Dos32 extender reflects physical addresses into another set of special
  321. address pages.  To find the logical address from physical, you have to add
  322. the value of the special _zero varible from the SYSTEM unit to the physical
  323. address.
  324.  
  325. For example:
  326.  
  327.         procedure clr_video (filler: char);
  328.            var i: integer;
  329.         begin
  330.            for i := 0 to 80*25-1 do
  331.                mem [_zero+$B8000+i*2] := filler;
  332.         end;
  333.  
  334. This procedure fills the video memory of the VGA adapter with the
  335. filler symbol.
  336.  
  337. Note that the linear address $B8000 is used as the physical address - not
  338. the segment address $B800.
  339.  
  340. Some another special variables are described in the SYSTEM unit.
  341. The _psp variable contains the logical 32-bit address of the PSP of the
  342. program, and the _environ variable contains the environment address.
  343.  
  344. Although you can access the interrupt vectors by using this method,
  345. we do not suggest doing this.
  346.  
  347.  
  348.     Also keep in mind that MS-DOS interrupt handlers use memory
  349.     addresses in the 1st mb of physical memory while your program
  350.     and its data are loaded beyond the 1st mb. DOS32 intercepts
  351.     and correctly handles some, but not all, calls to MS-DOS.
  352.     Thus, if you are using Intr() or MsDos() calls, or call MS-DOS from
  353.     the assembler, you will need to modify the code.
  354.  
  355.     Additional details about this and related subjects can be found in
  356.     DOS32.DOC and API.DOC in subdirectory DOS32.
  357.  
  358.              Calling conventions
  359.              -------------------
  360.  
  361. Calling conventions match those in Borland Pascal with the following
  362. differences:
  363.  
  364.      all parameters use 4 bytes on the stack, or a multiple of 4 (BP:2)
  365.  
  366.      all procedures must preserve the contents of registers ebx, ecx, edx,
  367.      ds, and es!
  368.  
  369.      the direction bit should be cleared after the exit from a procedure,
  370.      if it has been modified by it.
  371.  
  372.  
  373.                 Language syntax of TMT Pascal/Fast:
  374.                 -----------------------------------
  375.  
  376. While the Language syntax of TMT Pascal/Fast is in general compatible with
  377. BP 7.0, there are some differences. Below is the list, divided into three
  378. groups: limitations, extensions, and incompatibilities.
  379.  
  380.  
  381.    1. Limitations:
  382.  
  383. Not implemented are MARK and RELEASE.
  384.  
  385. The INLINE() operator is implemented in a partial form:
  386.     INLINE (byte/byte/...);
  387. (No references to variables/constants are allowed).
  388.  
  389. The import of object modules does not support all 32bit object formats.
  390. We recommend using TASM which is fully supported (except for
  391. the use of segmented addresses, which is not needed in the flat model).
  392.  
  393.  
  394.    2. Extensions:
  395.  
  396. ADA-style comments are supported:  -- comment
  397. For example:
  398.  
  399.       space := ' ';  -- initialize filler char
  400.  
  401.  
  402.  
  403. Almost everywhere where Pascal's syntax allows a type identifier, we
  404. also allow a type descriptor. The compiler will produce a warning if you
  405. use this feature.
  406.  
  407. !!! Keep in mind that the rules of type equivalence stay in force.
  408.  
  409. Procedural values contain the address of the local environment (frame).
  410. Thus, any local procedures can be used in procedural values. Procedural
  411. declaration in the style
  412.  
  413.     procedure p (function f (a:real):real); ...
  414.  
  415. are also realized.
  416.  
  417.  
  418. The procedural value from a method of object can be obtained by
  419. selecting this method from some object value (not from a type). The
  420. parameters of this procedural value must match the parameters of the
  421. method.  The invocation of such a procedural value is an invocation of the
  422. corresponding method of the object.  The reference to the object is
  423. transferred through the base of the procedural value.
  424.  
  425. You can use only global procedural values to initialize a type constant.
  426.  
  427. !!! Procedural values may be used only while the environment where
  428. they were formed is still in existence.  Thus, for local procedures
  429. --- until the exit from the block, in which they are described; for
  430. methods --- while the underlying object still exists.
  431.  
  432. see also "incompatibilities."
  433.  
  434. With TMT Pascal you can use any statement as a procedure body,
  435. except for the assignment and the procedure calls.
  436.  
  437. The RESULT variable in the body of such functions denotes the variable
  438. that contains the return value.  The RESULT is of the function return type
  439. and may be used as a variable without any restrictions.
  440.  
  441. With TMT Pascal you can enter the procedure body directly as a procedure
  442. parameter.  The procedure or function header (if not specified) takes the
  443. procedural parameter type.  If the procedure header is specified, the
  444. procedure name is omitted.  Example:
  445.  
  446. function integral (function f (a:real):real; low, high, step: real): real;
  447. begin ... end;
  448.  
  449.     ...
  450.     writeln (integral (
  451.          function (x:real):real; begin result := sqrt (x) end,
  452.     0, 10, 0.1));
  453.  
  454.     writeln (integral (begin result := sqrt (a) end, 0, 10, 0.1));
  455.  
  456.     writeln (integral (
  457.          function;        -- function keyword needed
  458.              var x: real; -- for local declaration
  459.          begin x := sqrt (a); result := x end,
  460.     0, 10, 0.1));
  461.  
  462.     writeln (integral (
  463.          declare;         -- other way
  464.              var x: real; -- for local variable declaration
  465.          begin x := sqrt (a); result := x end,
  466.     0, 10, 0.1));
  467.  
  468. TMT Pascal allows exit from a local procedure to the one that contains it.
  469. This feature is listed in the Pascal's ANSI standard but not realized in
  470. BP. Together with procedural values, this is very useful for error handling:
  471.  
  472. Program test;
  473.     Var on_eof: procedure;
  474.     Function read_char: char;
  475.         Var c: char;
  476.     Begin
  477.         If Eof (Input) Then on_eof;
  478.         read (c);
  479.         read_char := c;
  480.     End;
  481.  
  482.     Procedure p;
  483.         Label eof_reached;
  484.         Procedure go_eof; Begin goto eof_reached; End;
  485.     Begin
  486.         on_eof := go_eof;
  487.         While True Do Write (read_char);
  488.     Eof_reached:
  489.         Writeln ('*** EOF ***');
  490.         on_eof := NIL;
  491.     End;
  492.  
  493. Begin
  494.     p;
  495. End.
  496.  
  497. Restriction: BREAK and CONTINUE operators cannot be used to exit
  498. from a procedure. Use GOTO instead.
  499.  
  500. Example:
  501.  
  502.         for i := 1 to 10 do
  503.             writeln (integral (  -- function integral from previous example
  504.                 if a < 0 then break else result := sqrt (a), -- incorrect
  505.             i, i + 1, 0.01));
  506.  
  507.         declare
  508.             label L;
  509.         begin
  510.             for i := 1 to 10 do
  511.                 writeln (integral (
  512.                     if a < 0 then goto L else result := sqrt (a), -- correct
  513.                 i, i + 1, 0.01));
  514.         L: end;
  515.  
  516. Functions may return any values of any type, including structures and arrays.
  517.  
  518.  
  519. The new operator DECLARE
  520.  
  521.    DECLARE
  522.        <declaration part>
  523.    BEGIN
  524.        <statement list>
  525.    END
  526.  
  527.  
  528. allows one to describe local variables and procedures anywhere in the
  529. program.  Use of "DECLARE" leads to more readable programs and conserves
  530. the stack space.
  531.  
  532. Functions length, chr, ord may be used as variables. For example:
  533.  
  534.          chr (i) := ' ';   is equivalent to   i := ord (' ');
  535.          ord (c) := 255;   is equivalent to   c := chr (255);
  536.          length (s) := 10; is equivalent to   s [0] := chr (10);
  537.  
  538.  
  539. The main program may contain "interface" and "implementation".
  540. This allows access to the variables of the main program from other
  541. modules:
  542.  
  543.     Program test;
  544.     Interface
  545.        Var global: Integer;
  546.     Implementation
  547.        Uses Unit_test;
  548.     Begin
  549.        Unit_test.write;
  550.     End.
  551.  
  552.     Unit Unit_test;
  553.     Interface
  554.         Procedure Write_global;
  555.     Implementation
  556.         Uses test;
  557.         Procedure Write_global;
  558.         Begin
  559.             Write (test.global);
  560.         End;
  561.     End.
  562.  
  563.  
  564. !!! Here the name of the file that contains the text of the main program
  565. must be identical with the name that follows the keyword "program".
  566.  
  567. New type: DWORD - an unsigned 32-bit integer (same as unsigned long in C).
  568. It can be useful in many cases, but keep in mind that during arithmetic
  569. operations between DWORD's and LONGINT's both arguments are cast to
  570. LONGINT's. This may cause an error.
  571.  
  572. ABSOLUTE may refer to fields of records and objects.  Also, the
  573. address of a global record/object field can be used within the initialization
  574. of typed constants.  Furthermore one can use recursive initialization:
  575.  
  576. type rec = record
  577.                next: ^rec;
  578.                buffer: array [1..10] of char;
  579.                buf_adr: pointer;
  580.            end;
  581.  
  582. const cyclic: rec = (next: @cyclic; buf_adr: @cyclic.buffer);
  583.  
  584. In initialization of structures and objects the fields may go in
  585. an arbitrary order. If a field is not listed, it is zeroed up.
  586.  
  587. The syntax of the STR operator has been extended:
  588.  
  589.     STR (value[:width[:precision]], ..., dest);
  590.  
  591. Here STR (name:2, ':', ext:3, dst); is equivalent to
  592.  
  593.         STR (name:2, temp1);
  594.         STR (':',    temp2);
  595.         STR (ext:3,  temp3);
  596.         dst := temp1 + temp2 + temp3;
  597.  
  598. Negative field widths in WRITE, WRITELN, and STR left align the value within
  599. its field.
  600.  
  601. !!! The Strings unit contains additional functions which may be more
  602.     convenient than the STR operator.
  603.  
  604.  
  605. +++0.30
  606.  
  607.      Multidimensional open arrays:
  608.  
  609. You can now use in procedure parameters and functions descriptions
  610. "array (<dim>) of <type>", where <dim> is a positive integer constant, defining
  611. the number of dimensions, ánd <type> is the type of the array elements.
  612. To determine the upper bounds of the array, use the "high (array)" function.
  613. It returns a vector of longints ("array [0..<dim>-1] of longint") containing
  614. the upper bounds. The lower bounds are always set to 0. The vector of the lower
  615. bounds can be obtained with a similar function "low".
  616.  
  617. Example:
  618.  
  619.  
  620. procedure print_vector (v: array (1) of double);
  621. var i: integer;
  622. begin
  623.     for i := 0 to high (v) [0] do write (v [i]:10:6, ' ');
  624.     writeln;
  625. end;
  626.  
  627. procedure print_matrix (m: array (2) of double);
  628. var i: integer;
  629. begin
  630.     for i := 0 to high (m) [0] do print_vector (m [i]);
  631.     writeln;
  632. end;
  633.  
  634. const a: array [1..3, 1..3] of double = ((1,0,2),(2,1,0),(1,2,1));
  635.  
  636. begin
  637.     print_matrix (a);
  638. end.
  639.  
  640. You can find an example program for solving a system of linear equations in
  641. the directory "EXAMPLES\LIN_EQ".
  642.  
  643. ---0.30
  644. +++0.40
  645.          NEW!!!: User defined operations.
  646.  
  647. TMT Pascal allows redefining of the standard operations on predefined types and ¿
  648. overloading of these operationg for new types. For this, we use the construction
  649.  
  650.     OVERLOAD:
  651.  
  652. The syntax is:
  653.  
  654.     OVERLOAD op_sign = qualified procedure identifier;
  655.  
  656. Where the op_sign is one of the standard operation symbols:
  657.  
  658.      + - / * = <> < > <= >= AND OR XOR SHL SHR MOD DIV IN NOT
  659.      +:=   -:=   *:=   /:=
  660.  
  661. When a re-defined operation is used, TMT Pascal uses the last definition that
  662. could be applied toward operants of given types. For example, this fragment
  663.  
  664.     FUNCTION add2_rr (a, b:    REAL):    REAL; result := (a + b) * 2;
  665.     FUNCTION add2_ii (a, b: INTEGER): INTEGER; result := (a + b) * 2;
  666.  
  667.     OVERLOAD + = add_rr;
  668.     OVERLOAD + = add_ii;
  669.  
  670. redefines the "+" operation. Notice that the order of OVERLOAD's is important.
  671. The reverse order
  672.  
  673.     OVERLOAD + = add_ii;
  674.     OVERLOAD + = add_rr;
  675.  
  676. will cause "add_rr" used *always* since integers can always be cast into
  677. reals.
  678.  
  679. In the SOURCES subdirectory you can find the source of the COMP module which
  680. realizes the complex numbers and defines the operations on them.
  681.  
  682. Operations +:=, -:=, *:= and /:= have the lowest precedence (lower, than the comparison
  683. operations) and are right-associative. The operations "+:=" and "-:=" are
  684. predefined for all integer and real types; the operations "*:=" and "/:="
  685. are predefined for all real types, with the obvious meaning.
  686.  
  687. See also description of Strings unit.
  688.  
  689.      NEW: Iterated typed array constats:
  690.  
  691.      you can use the notation "..." in the array initialization.
  692. The ellipses should be the last element in the initialization list. If
  693. used, the remaining elements of the array are filled up with the
  694. last given value that preceded the ellipses. Ellipses cannot be the first
  695. element of the initialization list.
  696.  
  697. Example:
  698.  
  699. const a: array [1..10, 1..10] of integer = (
  700.     (1,...), (2,...), (3,...), (4, 5, 6, ...), (0, ...), ...
  701. );
  702.  
  703. fills up the 10 by 10 array as follows:
  704.  
  705.         1 1 1 1 1 1 1 1 1 1
  706.         2 2 2 2 2 2 2 2 2 2
  707.         3 3 3 3 3 3 3 3 3 3
  708.         4 5 6 6 6 6 6 6 6 6
  709.         0 0 0 0 0 0 0 0 0 0
  710.         0 0 0 0 0 0 0 0 0 0
  711.         0 0 0 0 0 0 0 0 0 0
  712.         0 0 0 0 0 0 0 0 0 0
  713.         0 0 0 0 0 0 0 0 0 0
  714.         0 0 0 0 0 0 0 0 0 0
  715.  
  716. ---0.40
  717.  
  718.     3. Incompatibilities:
  719.  
  720. Procedural values is 8 bytes long and has the following format:
  721.  
  722. 0   +-----------------------+
  723.     | The entry point       |
  724. 4   +-----------------------+
  725.     | The local environment |
  726. 8   +-----------------------+
  727.  
  728. However, a pointer to a procedure is only 4 bytes long and contains only the
  729. address of the entry point. The @ operator verifies that the procedure is
  730. global. Otherwise a range error is generated.
  731.  
  732. Furthermore, the stack frame structure and parameter passing conventions
  733. differ from those in BP.
  734.  
  735. Thus the approach used in TVision and CLassLib for writing iterators
  736. cannot be used. However, we offer this correct and reliable (and more
  737. standard) way:
  738.  
  739.      Type list = object
  740.                      next: ^list;
  741.                      procedure for_all (procedure body (var v));
  742.                  end;
  743.  
  744.      Procedure list.for_all;
  745.          Var p: ^list;
  746.      Begin
  747.          p := @self;
  748.          repeat
  749.              body (p);
  750.              p := p^.next;
  751.          end;
  752.      End;
  753.  
  754.      ...
  755.  
  756.      Type int_list = object (list)
  757.                          value: integer;
  758.                          function first_positive: ^int_list;
  759.                      end;
  760.  
  761.      Function int_list.first_positive;
  762.          Label OK;
  763.          Var res: ^int_list;
  764.          Procedure do_item (var v);
  765.          Begin
  766.              If int_list (v).value > 0 Then
  767.              Begin
  768.                  res := @v;
  769.                  GoTo OK;
  770.              End
  771.          End;
  772.      Begin
  773.          res := nil;
  774.          for_all (do_item);
  775.      OK:
  776.          first_positive := res;
  777.      End;
  778.  
  779.      ...
  780.  
  781.  
  782.  
  783. Since in the flat model there are no segments, SEG() always returns 0,
  784. while PTR() ignores its first parameter.
  785.  
  786. !!! Be careful with these functions: in practice, any use of PTR() or SEG()
  787.     in your program may require a program modification.
  788.  
  789. Pseudo-array Mem and MemW are used as follows:
  790.  
  791.     i := MemW [<linear address>]
  792.  
  793. Note that the segment is not given.  Furthermore, the pseudo-arrays
  794. MemD and PortD of type DWORD are available.
  795.  
  796. See "Memory organization" for more details.
  797.  
  798.            Built-in assembler
  799.            ------------------
  800.  
  801. The built-in assembler of TMT Pascal Lite is 32-bit.  It is compatible
  802. with the BP's built-in assembler with the following differences:
  803.  
  804. Since the program created by the Pascal Lite is executed in the flat
  805. model, the far call and jump commands as well as the @Code and @Data symbols
  806. are not implemented.
  807.  
  808. The ret command:
  809.  
  810. The ret command without arguments is considered as a ret <parameter block
  811. size> command.  If you need to write the ret command without size you should
  812. set 0 explicitly:
  813.  
  814.       ret 0
  815.  
  816. Code-procedure
  817.  
  818. Besides the assembler-routine you can use the code-routine.  It has the
  819. following differences: the compiler doesn't emit the frame command on
  820. enter and return from the routine (including the ret command), and the local
  821. parameters are based on ESP on the moment of entry.
  822.  
  823. Example:
  824.  
  825.     function hi (n: word); code;
  826.     asm
  827.         mov al, byte ptr [n+1]
  828.         ret
  829.     end;
  830.  
  831.  
  832.            Supplied units:
  833.            ---------------
  834.  
  835. The following units are included:
  836.      SYSTEM.FPx - standard library functions
  837.         DOS.FPx - MS-DOS and OS/2 system interface.
  838.                   Corresponds to the DOS unit of BP.
  839.         CRT.FPx - Text mode screen interface.
  840.                   Corresponds to the CRT unit of BP.
  841.       USE32.FPx - Define type Integer as 32-bit etc.
  842.    ERRCODES.FPx - Run-time error codes.
  843.       DEBUG.FPx - Some debugging code.
  844.     STRINGS.FPx - String handling functions.
  845.                   Corresponds to the STRINGS unit of BP.
  846.      OS2ORD.FPx - contains ordinal numbers for OS/2 functions
  847.     DOSCALL.FPx - contains declaration OS/2 API procedures
  848.    OS2PMAPI.FPx - contains declaration OS/2 PM API procedures
  849.  
  850. Besides these modules, the distribution includes DOSCALL.FPD and ARG.FPD,
  851. which are needed for linkage.  These modules should not be called by the user.
  852.  
  853.  
  854.            The DOS Unit
  855.            ------------
  856.  
  857. This corresponds to the DOS unit of BP.
  858.  
  859. Differences:
  860.  
  861.  Type FarPointer = record ofs: pointer; seg: word end;
  862.  
  863.  The function GetIntVec has the following syntax:
  864.      procedure GetIntVec (IntNo: Byte; var Vector: FarPointer);
  865.  
  866.  and not
  867.      procedure GetIntVec (IntNo: Byte; var Vector: Pointer);
  868.  
  869.  New procedures:
  870.  
  871.      procedure GetIntVecFar (IntNo: Byte;   var Vector: FarPointer);
  872.      procedure SetIntVecFar (IntNo: Byte; const Vector: FarPointer);
  873.  
  874.     GetIntVec is equivalent to GetIntVecFar().
  875.  
  876.     SetIntVec is equivalent to SetIntVecFar(), but uses in the segmented
  877.       address the current CS.
  878.  
  879. A header of an interrupt procedure should have the following form:
  880.  
  881. procedure handler (
  882.     eip, eax, ecx, edx, ebx, esp, ebp, esi, edi: dword;
  883.     gs, fs, es: word
  884. ); interrupt;
  885.  
  886.  
  887. The Registers type has this structure:
  888.  
  889.  type Registers =
  890.     record
  891.         edi, esi, ebp, _res : dword;
  892.     case boolean of
  893.         true:  (ebx, edx, ecx, eax: dword;
  894.                 flags, es, ds, fs, gs, ip, cs, sp, ss: word);
  895.         false: (bl, bh, b1, b2, dl, dh, d1, d2, cl, ch, c1, c2, al, ah: byte);
  896.     end;
  897.  
  898.  
  899.  
  900. !!! When using Intr() and MsDos(), keep in mind that the DOS
  901.     interrupt handlers can deal only with the addresses from the 1st
  902.     megabyte of memory.
  903.  
  904.  
  905.            The CRT unit
  906.            ------------
  907.  
  908. This unit corresponds to the CRT unit of BP.
  909.  
  910.            The USE32 unit
  911.            ------------
  912.  
  913. This unit contains redefinitions of integer types for 32-bit computing as follow:
  914.  
  915.     type
  916.       SmallInt   = System.Integer;
  917.       SmallWord  = System.Word;
  918.       Integer    = System.Longint;
  919.       Word       = System.Longint;
  920.  
  921.     const
  922.       MaxInt     = high(longint);
  923.  
  924.     type
  925.       PByte      = ^Byte;
  926.       PWord      = ^Word;
  927.       PLongint   = ^Longint;
  928.       PSmallInt  = ^SmallInt;
  929.       PSmallWord = ^SmallWord;
  930.  
  931.  
  932.            The ERRCODES unit
  933.            -----------------
  934.  
  935. This unit contains constants for error codes, given by RUNERROR(),
  936. and the error_msg(code: Word): String, function that decyphers the error code.
  937.  
  938.  
  939.            The DEBUG unit
  940.            --------------
  941.  
  942. This module prints out the error code and the call stack in case of a
  943. run-time error. The stack is printed as follows:
  944.  
  945. RunError #201 (range check error)
  946. Calls stack:
  947. SYSTEM.BOUND_ERROR [chk_fun.inp(21) at 0000000A]
  948. TEST.ASSN [TEST.PAS(61) at 00000015]
  949. TEST.TEST [TEST.PAS(82) at 0000001D]
  950.  
  951. To use DEBUG, simply list it in the USES clause of the main program.
  952.  
  953. This module is supplied with source.
  954.  
  955. Using the debug UNIT increases the .exe module size
  956.  
  957. !!! Note: call of a procedure with a NULL address is currently diagnosed as
  958.     an arithmetic overflow.
  959.  
  960.            The STRINGS unit
  961.            ----------------
  962.  
  963. This unit corresponds to the STRING unit of BP.
  964. It also contains additional functions:
  965.  
  966. Function hex (n: DWord   ): String [12];
  967.     -- prints the argument in hex.
  968.  
  969. Function whl (n: LongInt ): String [12];
  970.     -- prints the argument as a signed integer.
  971.  
  972. Function uns (n: DWord   ): String [12];
  973.     -- prints the argument as an unsigned integer.
  974.  
  975. Function fix (x: Extended; pr: LongInt): String [15];
  976.     -- prints a real with fixed point. pr is the number of digits after the
  977.        decimal point.
  978.  
  979. Function align (str: String; width: LongInt): String;
  980.     -- pads the argument up to width with spaces.
  981.        spaces are on the right if width>0, and on the left otherwise.
  982.  
  983. +++0.40
  984.       Additional functions defined in STRINGS:
  985.  
  986.       FUNCTION Dup_SI (CONST s: STRING; n: INTEGER): STRING;
  987.           - copies the string "n" times
  988.  
  989.       FUNCTION Dup_æI (ß: CHAR; n: INTEGER): STRING;
  990.           - creates the string by repeating character "c" "n" times.
  991.  
  992.       These functions are defined as operations:
  993.  
  994.             OVERLOAD * = Dup_SI;
  995.             OVERLOAD * = Dup_CI;
  996.  
  997.       For example, you can write 'ab'*4 instead of 'abababab'.
  998.  
  999.       FUNCTION AppendStr (VAR dst: STRING; CONST src: STRING);
  1000.           - appends "src" at the end of "dst"
  1001.  
  1002.       FUNCTION AppendStrC (VAR dst: STRING; src: CHAR);
  1003.           - appends character "src" to the end of string "dst"
  1004.  
  1005.       These functions are defined as operations:
  1006.  
  1007.             OVERLOAD +:= = AppendStr;
  1008.             OVERLOAD +:= = AppendStrC;
  1009. ---0.40
  1010.  
  1011.            The OS2ORD unit
  1012.            ---------------
  1013.  
  1014. This unit is valid only for OS/2. It contains ordinal number for
  1015. OS/2 system DLLs
  1016.  
  1017.  
  1018.            The DOSCALL unit
  1019.            ----------------
  1020.  
  1021. This unit is valid only for OS/2. It contains the declaration of the OS/2
  1022. API system procedures.
  1023.  
  1024.            The OS2PMAPI unit
  1025.            -----------------
  1026.  
  1027. This unit is valid only for OS/2. It contains the declaration of the OS/2
  1028. presentation manager API procedures.
  1029.  
  1030.  
  1031.                    Possible problems during usage
  1032.                    ------------------------------
  1033.  
  1034.  
  1035.     DOS/Ext programs, generated by TMT Pascal, abend under OS/2. Correction:
  1036.      - ensure that in "memory settings" the EMS_MEMORY_LIMIT is not equal to 0.
  1037.  
  1038.  
  1039. +++0.33
  1040.                    Run-time errors codes
  1041.                    -------- ------ -----
  1042.  
  1043.   1    Invalid function number
  1044.   2    File not found
  1045.   3    Path not found
  1046.   4    Too many open files
  1047.   5    File access denied
  1048.   6    Invalid file handle
  1049.  12    Invalid file access_code
  1050.  15    Invalid drive number
  1051.  16    Cannot remove current directory
  1052.  17    Cannot rename across drives
  1053.  18    No more files
  1054. 100    Disk read error
  1055. 101    Disk write error
  1056. 102    File not assigned
  1057. 103    File not open
  1058. 104    File not open for input
  1059. 105    File not open for output
  1060. 106    Invalid numeric format
  1061. 150    Disk is write protected
  1062. 151    Bad drive request struct length
  1063. 152    Drive not ready
  1064. 154    CRC error in data
  1065. 156    Disk seek error
  1066. 157    Unknown media type
  1067. 158    Sector not found
  1068. 159    Printer out of paper
  1069. 160    Device write fault
  1070. 161    Device read fault
  1071. 162    Hardware failure
  1072. 200    Division by zero
  1073. 201    Range check error
  1074. 202    Stack overflow error
  1075. 203    Heap overflow error
  1076. 204    Invalid pointer operation
  1077. 205    Floating point overflow
  1078. 206    Floating point underflow
  1079. 207    Invalid floating point operation
  1080. 208    Overlay manager not installed
  1081. 209    Overlay file read error
  1082. 210    Object not initialized
  1083. 211    Call to abstract method
  1084. 212    Stream registration error
  1085. 213    Collection index_out of range
  1086. 214    Collection overflow error
  1087. 215    Arithmetic overflow error
  1088. 216    General protection fault
  1089. 217    Invalid operation_code
  1090. 300    File io error
  1091. 301    Nonmatched array bounds
  1092. 302    Non local procedure pointer
  1093. 303    Procedure pointer out of scope
  1094. 304    Function not implemented
  1095. 305    Breakpoint error
  1096. 306    Break by ctrl/C
  1097. 307    Break by ctrl break
  1098. 308    Break by other process
  1099. 309    No floating point coprocessor
  1100.  
  1101. ---0.33
  1102.