XTDLIB/FPC alias THE TOOLKIT

(C) Marco van de Voort 1998,1999 Copyright data

Version (the current I hope) : 0.18. Version of TOM's libraries : ?-1-99

(Links to ASCII docs not available in Online version)

A lot of FPC and pascal Links page IMPORTANT INFORMATION (What is this?)
XTDLIB homepage(INTERNET LINK) Thomas Schatzl's page (CPU, MEMORY and DPMI units, now bundled in XTDFPC
Historyfile (ASCII) FPC Versions etc
Mail Marco van de Voort (Rest of XTDFPC +packaging) Mail Thomas Schatzl (CPU,DPMI,MEMORY and FARMEM + demoes)

Unit Index

Several units don't have a manual yet. This is because I'm porting all documentation to (La)Tex, and therefore stopt creating new unit documents

Syseq.incConditionals (TOM) Memory moving memory and extra MMX support
ECRC32 Fast CRC32 checksums,compatible with ARJ and ZIP CRC codes. (TOM) DPMI DPMI unit, a (better) alternative for Go32
EDate Calendar functions/Date handling
EDirTree recursive file and directory scanning
EDOS Dos specific stuff
EFIO File and filename routines
ELib Lowlevel and misc. procedures
EPasStr Pascal and ANSI String routines
EStrings PChar routines
EWindow handle based textwindowing
WinProc Generic interfacing routines

Other comments:



Important information.

Dates are always in Dutch format (dd-mm-yy)



Linux

Linux and other compability issues

(I'm quite fond of assembler, and have no experience on other platforms than intel (and C=64), so all this is basically strictly for intel. Right now, almost all routines have Pascal equivalents under some conditional code. See About Assembler for more details about the assembler/pascal conditional system)

EWindow works only with BP, FPC/Go32V2 and FPC/Linux, but could be made to work with anything which has a (virtual) screen like the DOS screen, or with a sophisticated Crt unit that maintains such a virtual screen (like FPC/Linux' Crt). If your system has a different kind of textscreen (e.g. text and attributes apart), that requires a bit more work, but is possible. An OS/2 port is in the works, and Go32V1 is untested, but I think it will work.

Textwindowing on terminal-driven screens like Linux are a lot more difficult to implement. Luckily, Ewindow is based on Crt, and when imported, Linux' Crt controls all output, and keeps a copy in an internal virtual screen. I moved the virtual screen to the interface of the Linux Crt source, and also a procedure to quickly set the color. The FPC rtl team took my suggestion seriously, and newer snapshots (0.99.9, after mid-october) have the virtual screen exported, so you don't have to modify the RTL anymore to use EWindow under Linux.

EWindow has an ansi-code in the initcode which should revert to standard IBM codes, which fixes the problem with the frames.

I'm not entirely a novice as far as Linux is concerned, but I'm more a Linux user and maybe a bit a system-administrator than a programmer. I won't be able to implement Linux code for OS-dependant parts without help. So if you have something, send it in, with instructions, or comment it heavily. Please remember that I don't understand C!

OS/2, I probably never going to support it myself. However if corrections will make the sources (more) OS/2 compatible then send them to me, and I will include them.

moduleLinux compability status
EPasStrBoth assembler and pascal versions are compatible with Linux, on an Intel. On a non intel machine, use the Pascal code.
EStringsSame structure and status as EPasStr
EDateAssembler module, no OS-dependant problems expected. Currently the Pascal equivalents are enabled, since the unit has problems with smartlinking.
EWindowsUses DirectScreenwrites and -reads under Dos. GotoXY/Textcolor/Write under Linux. Reading of the Linux screen is implemented by reading Linux-Crt's internal screen. Also compiles under BP, and OS/2 compability is being prepared
EDirTreeCompiles and works under Linux, but is FindFirst/FindNext based, not GLOB based, so maybe it's a bit slow.
ECRC32Should work entirely under intel-Linux.
5 out of 5, not bad! :-)

The demo WINDTEST doesn't function when link dynamically with the standard libs.

Thomas' units (DPMI, CPU) are almost non-portable. This because they are mainly specially targeted on Go32v2/dos problems and phenomena. The only exception is farmem, which compiles. However since Linux is severely protected, I see no use for it (it would probably GPF the application).



About PAS and assembler procedures and the stackframe

Some procedures in some modules (EStrings, EDate, EPasStr and EDate) contain assembler routines. All units contain portable Pascal equivalents for almost all assembler routines.

Every unit containing assembler has a {$define Useasm} somewhere at the beginning of the file. If this is defined, and the global define I386 (the assembler is intel only) is defined, the assembler routines will be used FOR THAT UNIT. So you can turn using assembler on and off per unit with useasm, or globally with i386.

Currently, assembler is turned of for EDate, because of some problems with ATT syntax and smartlinking.

Some of the defines are set in syseq.inc, please read the comments in there

Some very old versions of the FPC compiler implement the ASSEMBLER keyword different, (0.99.5 and 0.99.6 older than august 1st). I removed all support for that, since those versions are really old. I suggest you use a newer snapshot, or revert to pascal by putting {$UNDEF I386} in syseq.inc.

Almost assembler is written for -Ratt mode, except some things ported from Dos in EDOS which is -Rintel. The main reason is that you can't access variables easily while using direct assembler. Variables local to the implementation of an unit get the unitname prefixed when smartlinking, and only a underscore when normal linking is used.

The makefiles and sources files should however automatically take care of this, there is no need to put -Ratt in your ppc386.cfg anymore



Filelist.

The Demoes

asmbeaut.ppA start for an inline assembler source beautifier
crctest.pp Calculates and displays the CRC32 of the file test.dat
dfree.pas Colorfull unix DF command for DOS. Use -Rintel to compile
dict.pas Isolates words from textfiles, and builds a complex binary tree.
dirtest.pp Displays all *.pp and *.pas files bigger than 50 bytes on the current disk, by building a tree into memory
filefind.ppFind a file using EDirTree.FileScan
findarch.ppTries to detect the filetype of every file in the current directory and below
indexer.ppEDirtree demo, used to make indexes for own CD-R's
keytest.ppUsed to generate codes for GetKey.
lfntodes.ppLongfilenames to 4DOS descript.ion SKELETON (still very simple)
lzhtest.ppDemo to test the LZH compression unit
myopt.ppAn own still very experimental commandline routine, for odd applications, when GetOpt doesn't suffice
unixtest.ppAn old debug-test. Calculate the unix-date for all dates in range 1970-2100, and convert them back to DDMMYY. Compare both dates, and report mismatches
windtest.ppDemo of Ewindow module.
Dependancies

The libraries

bpgo32.pas I use some unit Go32 routines in EWindow. This unit contains some alternatives for those Go32 routines to ease compiling EWindow under BP
complib.pp Dummy program used to compile all units with one PPC command.
ecrc32.pp Fast CRC-32 calculation
edate.pp Date handling
edirtree.pp Recursive directory handling
efio.pp Everything which operates on files
elib.ppLowlevel and Misc. routines.
lzhUnit for datacompression. Will be updated in the future with optimized assembler. Now straight SWAG copy, with some small fixes for an old FPC bug.
EPasstr.pp Pascal string handling
estrings PChar string handling
ewindow Handle based TextWindow module
pasasm.ppBarrel for outdated routines, not really a part of the actual libraries
syseq.incContains important conditional code for the libraries
Other files of interest

keys.inc (ASCII)Keyboard codes for ELib.GetKey
XtdHst.txt (ASCII)History file
readme.txt (ASCII)Quick install help
xtdlib.txt (ASCII)Old text-file documentation Outdated



History/Philosophy behind XTDLIB

The original, Modula2 (a pascallish language) Xtdlib was meant as a kind of SWAG for Modula2. The only difference was that it wouldn't be a bunch of loose, hardly ordened messages like SWAG, but a standarized, coherent library, a kind of secondary RTL on top of the normal RTL.

Since feedback was nearly zero (except for the TopSpeed buglist which was also maintained in the archive), and because it remained a 'Me, Myself and I' project, I changed the package to shareware. When I started playing with FPC, I ported some small routines to FPC. As that went fast and easy, I decided to translate all mostused routines to a FPC version.

The new philosophy is the same as the old one. Standarize the not entirely standard, but often used routines. The standard libraries of FPC barely reach beyond BP's. The FPC runtime library team decided to keep the routines as close to the original TP routines as possible, probably because of compability issues.

I asked them to add some routines, but they didn't want to change the original units, to ensure BP/TP compability, and suggested to either blend the routines in their platform-independant API, or to create a new project, with new units, which, in time (when it's beyond the ALPHA stage) would become part of the RTL.

This new part of the RTL would simply be called the Toolkit, all contributions are welcomed. My E-mail address is at the beginning of this page.

Currently Thomas Schatzl's most used units with some demoes are also included. Mainly because I wanted to use some of them in future own programs, and I wanted to keep XTDFPC an unpack-and-make package, without to much installing and additional package which have to be obtained. Also I can now easier crossreference the docs if I want. Assembler, and my coding style.

A lot of people (specially academic and C programmers) avoid assembler as long as they can. I don't. I can get away with it, because I am an hobby-programmer, and my time isn't paid. I heard the reasons for killing asm a dozen time, and though I don't fully agree, I can understand professional programmers point about assembler. However I think most of the reasons don't apply to free projects, as long as some portable code is still available. I'm a bit less fanatic with assembler as I used to be since FPC is multitarget, but I still have this opinion about assembler

I like assembler simply because I think small very-often used routines by a lot of people (like e.g. a rtl, often used stringroutines, datacompression ) should be done in assembler, it's faster and tighter, and those routines are used so much that it is worth the trouble. I often keep highlevel versions(often not optimized) in a separate archive to avoid portability problems. (FPC and BP, with their more advanced condtional system allow to keep the versions in one file)

If you dive into public code(like swag), you'll find numerous units which are Pascalled assembler (loading System.registers and Intr calls is the only thing which is done). Personally I think that is bad programming. The dos-interrupts (and the bios interrupts even more) were designed to be called in assembler, this of course doesn't apply to FPC-pascal. INT in FPC calls the protected mode interrupt.

My own assembler coding style isn't that great. Any comments are appreciated, but will be used when reviewing or programming new assembler. I'm not gonna search all old assembler to gain two jiffies or so:-)

Procedure and unit names

The names of the procedures aren't fixed yet. For now, I have retained the names in the Modula2-version of XTDLIB. If somebody has a coherent namesystem, with solid arguments in favour of the new system, I'm pricipally willing to change the procedure names. Often, procedurenames are based on SWAG, and already a bit standard.

This will have to happen fast. At the time of this (0.10) release, XTDFPC is downloaded almost daily, and I don't want to change all procedure names after a lot of people based their programs on the current names



Conditionals and Syseq.inc

To keep the routines compilable under various versions and platforms of FPC, and even on BP/TP, I defined some global (to entire library) conditionals in syseq.inc.

i386Intel-style processor(also AMD, Cyrix and NextGen), required for using the assembler.
If you don't $DEFINE this, the libraries will revert to the pascal-alternatives See also About assembler
LinuxCompling for a Linux system? Till now, this changes backward to forward slashes, and enables some Linux code in EWindow, this define also automatically enables CloseFind and disables DosFPC (This conditional has been removed, FPC defines it itself).
TurboSyseq.inc tests VER60 and VER70 defines (which are automatically set by BP/TP), and if one such define is found, syseq.inc $DEFINEs Turbo, so you'll know that this is Borland or Turbo Pascal specific code. Mainly used to avoid importing Go32 under TP, and to turn of assembler (Since it's 32-bit it won't work under TP/BP
DosFPCDepriated, and replaced by {$IFDEF Go32V2}, I decided to drop Go32V1 functionality.
CloseFindIndicates if Dos.FindClose is used after each Dos.FindFirst. Will be always true in the future, except under Turbopascal. It will be true under FPC-Dos when FindFirst is upgraded with LongFileNames. (the Win9x LFN system also requires FindFirsts to be closed) (You can undefine it for DOS, if you have compiled your RTL without LFN support, the so called RTL-Lite)
UseAsmThis define is local to the unit it's in. If you undefine it, no assembler will be used in that unit, even if i386 is defined. See also About assembler
OldLinuxWinUsed to select between two type of Crts. TRUE for version 0.99.8 and older, false for 0.99.9
The new Linux Crt has a pointer to the virtual screen and the screen-dimensions in the definition, for older versions you have to alter the Crt before EWindow works under Linux. If your 0.99.9 doesn't work, you'll have to upgrade to a newer snapshot or edit syseq.inc

That's it for now, but the number grows exponentionally :-)



Copyright and license data

This is the file COPYING.TXT blended into the documentation, it applies to the XTDLIB/FPC toolkit source files copyrighted by Marco van de Voort.

The source code of Free Pascal is distributed under the GNU General Public License (see the file COPYING(ASCII)) with the following exceptions:

If you didn't receive a copy of the file COPYING, contact:

      Free Software Foundation
      675 Mass Ave
      Cambridge, MA  02139
      USA
      
Suggestions, ideas ?? Please correct spelling mistakes in the license, if you see one.



Versions

It's hard to keep a source-archive compatible with every version and target, because the FPC compiler (and RTL) still change slowly but steadily.

I try to keep the toolkit compatible with

I don't say that it won't run on the other versions and targets, or that I don't support those other targets. However, I can't test on those targets myself, and everything for those targets is heresay, and untested.

The Borland Pascal 7.0 compability has been dropped, but single units might still be Borland compilable with a reasonable effort. Turn assembler off! (syseq should do that automagically)

Also often you have to turn of assembler for older targets, because the assembler reader is one of the things that changes most (at least until 0.99.10)

Notice

The Memory unit should be compiled with FPC Pascal (32-bit protected mode freeware DOS compiler) and a GNU assembler version of 2.9.1 or higher. (BEWARE that FPC 0.99.10 still packages AS 2.8.1!!!!, you can get the newer 2.9.1 on Thomas' page

Any testers for other OSes, or even the supported targets are welcomed!