POINT Software Programming

home *** CD-ROM | disk | FTP | other *** search

/ POINT Software Programming / PPROG1.ISO / pascal / visionix / read.me < prev next >

Wrap

Text File | 1993-12-29 | 28.1 KB | 893 lines

█▌ ▐█ █▌ ▄████▄ █▌ ▄████▄ █▌▄███▄ ▐█ █▌ █▌▐█▀ ▀█▌█▌▐█▀ ▀█▌ ███▀ ▀█▌ █▌ ▐█ █▌ ██▄▄▄ █▌██ ▐█ ██ █▌▄▄▄▄▄▄▄ ▄▄▄▄ ▄▄▄▄ ▄ ▄▄▄ ▐█ █▌ █▌ ▀▀▀██ █▌█▌ ██ █▌ █▌ █ █ █ █ █ █ ▀▄ ███ █▌▐█▄ ▄█▌█▌▐█▄ ▄█▌ █▌ █▌ █ █ █ █ █ █ ▀▄ ▐█▌ █▌ ▀████▀ █▌ ▀████▀ █▌ █▌ █ ▀▄▄▄▄▀ ▀▄▄▄▄▀ █▄▄ ▄▄▄▀ ──────────────────────── P ── A ── S ── C ── A ── L ──────────────────────── BETA Release 0.31 Copyright 1989-1993 Visionix ALL RIGHTS RESERVED December 28, 1993 About this Document ──────────────────────────────────────────────────────────────────────────── This document describes the arhictecture, overview, and implementation of the VisionTools for Pascal libraries, version 0.31 BETA. VisionTools is a - comprehensive - easy to use - flexible, multi-platform Pascal library package. VisionTools supports - Turbo Pascal 6.0 - Turbo Pascal for Windows - Turbo Pascal / Borland Pascal 7.0 VisionTools units work in - DOS - Protected mode - Windows - and OS/2. (Requires German OS/2 patch for TP/BP 7.0) In this document, we assume a working knowledge of structured programming concepts in general and the Pascal language in particular. This document is Copyright (C) 1993 by Visionix, with ALL RIGHTS RESERVED. Until such time as VisionTools is release outside of the BETA team, this release is the confidential and proprietary property of Visionix, and as such should not be distributed in any form without express written consent of Visionix. VisionTools Overview ──────────────────────────────────────────────────────────────────────────── VisionTools for Pascal is a comprehensive, easy to use, flexible multi-platform Pascal library package that supports DOS, DOS protected mode, Windows, and OS/2. Just how comprehensive is VisionTools? ────────────────────────────────────── VisionTools is comprised of over 40 units which implement over 800 functions. VisionTools includes library units for ANSI, Avatar, Doors, File copying, CRT API replacement and enhancement, Times and Dates, Debugging, DOS, Fonts, FOSSIL, General functions, text stream input, Keyboards, High-Level Math, Memory Management, Multi-Tasking, text stream output, Pointer & Mice, Resource Files, Serial Communications, File/Record Sharing, Sorting, Finite-State Machines, Strings, Text, Advanced Power Management, BIOS, CD-ROM, DPMI, EMS, XMS, MSCDEX, 8250/16450/16550 UARTs, Virtual DMA Services, OS/2 API importation, and more. What do we mean by Multi-Platform? ────────────────────────────────── We mean that VisionTools for Pascal supports all of the listed platforms by simply recompiling. Therefore, if your programs use VisionTools, you can port them to other platforms by doing nothing more than recompiling! VisionTools Units ───────────────── VisionTools consists of units of functions which fall into 9 categories: General Units VGENu General functions VMATHu High-level math functions VDATESu Time and date functions VDEBUGu Usefull debugging functions VRESFu Resource file functions VSORTu Sort functions VSTATEu Finite-State machine functions VSTRINGu String functions VSTRTXTu VTYPESu Sundry types and constants Console I/O Units VINu Text Stream Input functions VOUTu Text Stream (Presentation) output functions VCRTu Pascal CRT replacement and enhancement functions VANSIu ANSI functions VANSIIOu ANSI I/O filters and drivers for VOUTu VAVTIOu Avatar I/O Filters and drivers for VOUTu VFONTu Font redefinition functions VKEYbu Keyboard functions VPOINTu Mouse & Pointer functions Serial Communications Units VFOSu FOSSIL functions VUARTu 8250/16450/16550 UART functions VSERlu Low-level serial types VSERu Device-independent serial functions VSERhu High-Level serial functions Memory Management Units VEMSu Expandend Memory Services functions VXMSu eXtended Memory Services fucntions VMEMu Multi-platform memory management functions File System Units VCOPYu File copying functions VDOShu High-level dos functions VSHAREu File sharing & record locking functions VTEXTu Text file device drivers & functions Device Control Units VCDROMu CD-ROM data & audio functions VMSCDEXu MSCDEX based data & audio functions System Units VAPMu Advanced Power Management functions VMULTIu Multi-procedure / Multi-Threading / Multi-Tasking functions VEQUIPu Equipment determination functions VXPROTu Exit procedure stack functions DOS/Protected Mode/Windows Specific Units VBIOSu BIOS Data Area functions VDPMIu Dos Protected Mode Interface functions VVDSu Virtual DMA Services Units OS/2 Specific Units VMOUi OS/2 Mouse API Import Unit VKBDi OS/2 Keyboard API Import Unit VVIOi OS/2 Video I/O Import Unit About the Documentation ─────────────────────── This documentation is a preliminary version of the final documentation. The complete documentation was written on a hybrid system that uses PageMaker, Word for Windows, and custom "document/source code control system" written by Visionix. As you may have noticed, most of the documentation is mixed in with the source code of the actual units. The next BETA release will include a program to extract the documentation from the source and generate either Microsoft Rich Text Format (RTF), PageMaker Tagged Text Format (TTF), or normal ASCII document files which can be printed via a variety of word processing or editor packages. If you would like to generate seperate document files with this release, run the batch file MAKEDOCS.BAT. This batch file will run a program that will copy the interface and documentation comments from each unit to a file named <unitname>.INT If you have any questions what-so-ever, please be sure to contact Visionix via any of the methods listed at the end of this file. For extended documentation, refer to the extensive documentation and comments that are found in each unit. Using VisionTools with "BP for OS/2" ─────────────────────────────────── VisionTools fully supports "Borland Pascal for OS/2". "Borland Pascal for OS/2" is a patched version of BP 7.0 wherein the Windows support is patched to generate 16 bit OS/2 programs. All appropriate VisionTools units have been modified and tested on OS/2, and several units are included explicitly for OS/2. In case you don't have it already, the BP for OS/2 patch is available on VisionixBBS as BP7-OS2.ARJ. Contacting Visionix ─────────────────── BETA Reports To contact Visionix to report a bug, anamoly, or disturbance in the known fabric of the universe, fill in the enclosed BETA FORM (BETAFORM.TXT) and modem or mail it to one of the addresses below. BBS VisionixBBS (USA) (407) 872 1318 FidoNet 1:363/640 Internet f640.n363.z1.fidonet.org!visionix Internet killamac@ufcc.ufl.edu Postal Mail Visionix 1240 Golfview St. Orlando, FL 32804 USA Voice Visionix (407) 648 8851 General Units ──────────────────────────────────────────────────────────────────────────── VGENu General functions ────────────────────────────────────── The general functions unit consists of functions which fall into 8 categories: - Validation routines - Type conversion - Variable comparing and swapping - System and CPU - CRC - Soundex functions - Pointer functions - Misc. functions VMATHu High-level math functions ────────────────────────────────────── This unit implements a wide variety of higher-level math functions. These function fall into the following categories: - Algebraic - Trigonometry - Calculus - Statistical - Misc. other math VDATESu Time and date functions ────────────────────────────────────── VDATES is the collection of various date and time functions. Some features include: - Day of week, Leap Year, Days in month, and Daylight Savings. - Type validations. - DateTime (from DOS unit) is now called TDateTime (for Windows compat.). - TDateTime inc, dec, add, sub, and absolution difference. - Julian date <--> DateTime conversions (for your Date-math functions). - Packed DateTime extractions and conversions. - Stop Watch (TSwatch) for the time-of-day in seconds (with 100th second accuracy). TSwatch also has inc, dec, add, sub, and distance functions. - System Clock functions: clock ticks since midnight, setting system date and time, setting system alarm (these work with BCD parameters). - and much more... VDEBUGu Usefull debugging functions ────────────────────────────────────── This unit provides a simple set a functions which can be used to debug a program. It provides functions to write "information" lines to a specified text file. VRESFu Resource file functions ────────────────────────────────────── This is a text-based resoure retrieval library. This unit provides the ability to use an external text file for all text, integers, reals, menus, dialogs, colors, and boolean values used by a program. VSORTu Sort functions ────────────────────────────────────── This unit uses a generic sorting engine to allow for sorting many different predefined data types as well as user-defined structures. Some include ShortInt, Byte, Integer, Word, LongInt, String, PString, PChar, and Real types. VSTATEu State machine functions ────────────────────────────────────── This unit includes functions to assist in the creation and usage of finate state machine based programs. It includes functions to create state machines, add states to machines, track states, remove states, and execute state machines. VSTRINGu String functions ────────────────────────────────────── This unit implements a variety of functions for string allocation, usage, and management. It also includes a set of advanced functions that implement a generic "string-list" mechanism which supports string arrays, string pointer arrays, link-list string arrays, and PChar arrays. VSTRTXTu String Text File Driver ────────────────────────────────────── This unit implements a text file device driver that will write to a VSTRINGu string list. This provides a flexable mechanism to use the Write and WriteLn commands to format strings. VTYPESu Sundry types and constants ────────────────────────────────────── VTypesu is a unit that defines a variety of types, defines, and constants that are used throught the VisionTools libraries. Console I/O Units ──────────────────────────────────────────────────────────────────────────── VisionTools implements a comprehensive, flexible text console I/O architecture. The architecture works on a variety of "presentation protocols", such as ANSI, Avatar, OS/2 VIO, and normal CGA/EGA/VGA/Mono video memory. The architecture includes a Turbo Pascal CRT replacement unit which facilitates effortless porting of Pascal programs to OS/2 and ANSI/Avatar serial based applications. The console I/O architecture is based on the concept of channels and sub-channels. A channel is a "path" to a distinct console, which can have a different display than other channels, and sub-channels are branch-paths to "synchronized" consoles, which all have the same display. For more information, see the documentation in the VOUTu unit; wait for the next BETA (which includes a 20+ page tutorial), look at the demos and test programs, or call! We'll be happy to help. VINu Text Stream Input functions ────────────────────────────────────── The VINu unit implements the input functions for the VisionTools text-stream input/output architecture. The present implementation of VIN is an extremely simplified, one channel, no sub-channel, input version of VOUT. This unit has been rewritten and will be replaced with the full multi-channel input unit in the next BETA release. VOUTu Text Stream (Presentation) output functions ────────────────────────────────────── - VOUT functions. VOUT contains an extensive collection of video text output functions, such as VOutClrScr, VOutWriteString, VOutInsLine, VOutWindow, Etc. - Multiple channels. Every VOUT function takes a "channel handle". This tells VOUT which channel to perform the function on. "Multiple channels" can be used to perform operations on seperate video displays. For example, two seperate channels could be set up for the primary and secondary monitors. Commands sent to the first channel would go to the primary montior. Commands sent to the second channel would go to the secondary monitor. Each monitor would then have a different display. - Multiple sub-channels. Sub-channels are synchronzied branches from a channel. Sub-channels allow the same output commands to be "synchronized" on different video displays. For example, one channel could be created with two sub-channels. One sub-channel would be setup for the local video display, and another could be setup to send ANSI over a serial port. Commands to this channel would then be sent both to the local video display and out over the serial port. This could be used as the text-output interface for a BBS program or other host communications software. VCRTu Pascal CRT replacement and enhancement functions ────────────────────────────────────── VCRTu is a Turbo Pascal CRT replacement unit. It implements all of the functions found in the TP CRT unit, and adds many new functions. VCRTu is an interface layer on top of VOUTu and VINu. Calls to VCRTu functions are completed by calling the appropriate VOUTu or VINu function. VCRTu automatically creates a CRT output channel and a sub-channel which sends its output to the primary local video display. <<Whats all that mean>> Basically, VCRTu replaces CRT. VCRTu does all of its work through a fast, flexible, and comprehensive text input and output architecture which is based on the concept of text input and output channels and sub-channels. By default, VCRTu automatically creates a text output channel and sub-channel which goes to the primary video display, and a text input channel and sub-channel which goes to the keyboard. VCRT then does all of its work via these channels. For example, when you call ClrScr, VCRT calls VOutClrScr with the handle of the CRT output channel. When you call ReadKey, VCRT calls VInReadKey with the handle of the CRT input channel. By attaching filters to the CRT sub-channel you can enhance or modify the output capabilities of your application. For example, you can attach the AnsiFilter to the CRT sub-channel to make it possible to use ANSI commands in your Write or WriteLn statements. By creating new sub-channels off of the CRT channel, you can direct the output of your program to other devices, such as the serial port. This creates a flexable foundation for BBS programs or DOOR programs. For more information, see the VOUTu and VINu chapters. VANSIu ANSI functions ────────────────────────────────────── This unit mainly provides functions which generate ANSI command strings. Each function returns a string which is the ANSI command equivalent of the function. For example, The ANSIClrScr function returns the ANSI Clear screen command as a string, '<ESC>[2J'. VANSIIOu ANSI I/O filters and drivers for VOUTu ────────────────────────────────────── The VANSIiou unit contains only two procedures: ANSIFilter and ANSIOutDriverProc. As the names imply, ANSIFilter is a VOUT filter for ANSI commands, and ANSIOutDriverProc is an VOUT output driver for ANSI. For more information on text filters, drivers, sub-channels, etc., be sure to read the VOUTu and VINu documentation. VAVTIOu Avatar I/O Filters and drivers for VOUTu ────────────────────────────────────── NOTE! This BETA does not include the AVATAR driver procedure. It will be included in the next BETA! The VAVTiou unit contains only two procedures: AvatarFilter and AvatarOutDriverProc. As the names imply, AvatarFilter is a VOUT filter for Avatar 0+ commands, and AvatarOutDriverProc is an VOUT output driver for Avatar. For more information on text filters, drivers, sub-channels, etc., be sure to read the VOUTu and VINu documentation. VFONTu Font redefinition functions ────────────────────────────────────── The VFONTu unit implements functions to create and manage new text-mode character sets. The documentation for this unit will be enhanced in the next release. VKEYbu Keyboard functions ────────────────────────────────────── The VKeybu unit implements a variety of functions for the PC/AT keyboard. This unit also includes constants for most keyboard scan codes. VPOINTu Mouse & Pointer functions ────────────────────────────────────── VPointu implements a comprehensive, easy to use "mouse" function library that works under DOS, protected mode, and OS/2. Serial Communication Units ──────────────────────────────────────────────────────────────────────────── VFOSu FOSSIL functions ────────────────────────────────────── This unit implements a function for all commands in the FOSSIL specification. For more information, refer to the FOSSIL spec. This unit also implements FOSSIL functions which are specific to the X00 FOSSIL driver. Additionally, this unit impelements a function to interface the FOSSIL functions into the VSERu device-indepednent serial unit. This function, FosSerDriverProc, is a serial driver procedure for VDOSu serial channels. FosSerDriverProc can be specified as the serial-driver for a serial channel by calling VSerDriverNew and specifying FosSerDriverProc as the serial driver procedure VUARTu 8250/16450/16550 UART functions ────────────────────────────────────── This unit implements functions to interface with the PC/ATs 8250, 16450, or 16550 Univeral Asychronous Receiver/Transmitter, or UART chip. The UART chip is the PCs interface to the RS-232 world. Additionally, this unit impelements a function to interface the UART functions into the VSERu device-indepednent serial unit. This function, UartSerDriverProc, is a serial driver procedure for VDOSu serial channels. UartSerDriverProc can be specified as the serial-driver for a serial channel by calling VSerDriverNew and specifying UartSerDriverProc as the serial driver procedure. VSERlu Low-level serial types ────────────────────────────────────── This unit implements various low-level serial communication types and constants. VSERu Device-independent serial functions ────────────────────────────────────── The VSERU unit implements a comprehensive set of functions for serial communications. VSERhu High-Level serial functions ────────────────────────────────────── This unit implements a variety of high-level serial communications functions, which are based on the functions in VSeru. This overview will be enhanced in the next BETA release. Memory Management Units ──────────────────────────────────────────────────────────────────────────── VEMSu Expandend Memory Services functions ────────────────────────────────────── This unit implements a function for all commands in the EMS specification. The documentation for this unit will be enhanced in the next release. VXMSu eXtended Memory Services fucntions ────────────────────────────────────── This unit implements a function for all commands in the XMS specification. The documentation for this unit will be enhanced in the next release. VMEMu Multi-platform memory management functions ────────────────────────────────────── The VMemu unit implements 4 simple, cross-platform memory allocation functions. This unit has been rewritten to include support for both Windows and OS/2 GlobalAlloc/GlobalLock/GlobalFree functions. This unit will be replaced with the new unit in the next BETA release. The function interface, however, will remain the same. File System Units ──────────────────────────────────────────────────────────────────────────── VCOPYu File copying functions ────────────────────────────────────── VCOPYu contains two functions, VCopyFile and VCopyFileEx. The VCopyFile function allows you to copy files from one place to another. It supports wildcards, copy from/to date ranges; copy files with specified attributes, the ability to copy sub-directories, and more. The VCopyFileEx function does everything that VCopyFile does, with the added capability to have VCopyFileEx call a "call-back" procedure that you can specify when different VCopyFile events occur. (Such as: starting a new file, read error, write error, etc) VDOShu High-level dos functions ────────────────────────────────────── The VDOSHu unit implements various DOS oriented functions. More documentation will be added to this unit in the next BETA release. VSHAREu File sharing & record locking functions ────────────────────────────────────── This unit implements various file-share and record locking functions. It has been completely rewritten and will be replaced in the next BETA release. VTEXTu Text file device drivers & functions ────────────────────────────────────── This function implements a text file device driver which "strips" or ignores ASCII CTRL-Z (End Of File, EOF) markers. Device Control Units ──────────────────────────────────────────────────────────────────────────── VCDROMu CD-ROM data & audio functions ────────────────────────────────────── VCDROMu is a generic CD-ROM unit which currently works on MSCDEX, but which will be enhanced in the next VisionTools release to also support direct control of SCSI-2 CD-ROM drives without requiring MSCDEX. VCDROMus is handle based. Before you call any VCDROMu functions, you should call VCD_Open. VCD_Open takes two paramaters: "flags" which are currently unsed, and a "method list string" which tells VCDROMu which CD-ROM methods you wish to use. Currently, only MSCDEX is supported, so the method list string must be 'MSCDEX'. VMSCDEXu MSCDEX based data & audio functions ────────────────────────────────────── This unit implements MSCDEX dependent functions to control and play CD-ROM and CD-Audio discs. For more information, see the MSCDEX documentation. This overview will be enhanced for the next BETA release. System Units ──────────────────────────────────────────────────────────────────────────── VAPMu Advanced Power Management functions ────────────────────────────────────── This unit is an interface to the DOS Advanced Power Management functions. For more information, see the DOS Avanced Power Management specification which is available from Intel. The documentation for this unit will be enhanced in the next BETA release. VMULTIu Multi-procedure / Multi-Threading / Multi-Tasking functions ────────────────────────────────────── VMultiu implements a simple, procedure based, non-preemptive multitasking facility. THIS UNIT IS INCOMPLETE! In the next release, it will also implement a cross-platform multi-thread facility, and the ability to work with DesqView, OS/2 and Windows to evenly distribute time slices. VEQUIPu Equipment determination functions ────────────────────────────────────── This unit implements functions which return information about the equipment that is currently connected to the PC on which the unit is running. The documentation for this unit will be enhanced in the next release. VXPROCu Exit procedure stack functions ────────────────────────────────────── This procedure implements an "exit procedure stack" which manages a list of procedures which should be called when a Turbo Pascal application terminates. It provides functions to dynamically add and remove procedures to/from the exit stack. DOS/Protected Mode/Windows Units ──────────────────────────────────────────────────────────────────────────── VBIOSu BIOS Data Area functions ────────────────────────────────────── This unit maps a single pointer-variable onto the BIOS Data Area (BDA). located at segment $40. This pointer can then be used to access the BDA in a clean way. The unit works in real mode, protected mode, and Windows. For more information on the BIOS DATA area, consult any book which expains the IBM PC/AT BIOS in detail. VDPMIu Dos Protected Mode Interface functions ────────────────────────────────────── This unit implements a function for all commands in the DOS Protected Mode Interface 0.9 and 1.0 specifications. For more information, refer to the DPMI specification. (Intel Order No. 240977-001) Additionally, this unit impelements functions to assist in allocating and using protected mode to real mode "reflection buffers". Reflection buffers are used when calling a real mode BIOS routine from protected mode. The documentation for this unit will be enhanced in the next release. VVDSu Virtual DMA Services Units ────────────────────────────────────── The VVDSu unit implements functions for the Microsoft/IBM Virtual DMA Services (VDS) specification. The virtual DMA services specifications supplies services which allow for proper first and second party DMA operations on PC/AT computers which are running in virtual memory environments. It includes services to get the physical address of virtual memory locations; to get a scatter/gather list of virtualy fragmented memory buffers; to allocate DMA translation buffer, and more. OS/2 Specific Units ──────────────────────────────────────────────────────────────────────────── VMOUi OS/2 Mouse API Import Unit ────────────────────────────────────── This unit is a DLL import unit for the OS/2 Mouse API DLL. It imports all of the functions found in the OS/2 Mouse API DLL. VKBDi OS/2 Keyboard API Import Unit ────────────────────────────────────── This unit is a DLL import unit for the OS/2 Keyboard API DLL. It imports all of the functions found in the OS/2 Keyboard API DLL. VVIOi OS/2 Video I/O Import Unit ────────────────────────────────────── This unit is a DLL import unit for the OS/2 Video I/O API DLL. It imports all of the functions found in the OS/2 Video I/O API DLL.