HighSpeed Pascal 1.10 ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ Amiga Units ŻŻŻŻŻŻŻŻŻŻŻ HighSpeed Pascal now includes units which give access to all of the structures and library calls introduced in Release 2 of the operating system. These units, supplied on a fourth disk, include a number of new files and form a complete replacement for the 1.3 set. In addition to this, changes in the units themselves and disk organisation are documented below. Installation ŻŻŻŻŻŻŻŻŻŻŻŻ As shipped, both Program Disks are set up to use the Workbench 1.3 units. Due to the increased size of the 2.0 units, a minimum 1.5MB of RAM is recommended for their use. By following some of the suggestions on page 13 of the User Manual, 1MB users can also make use of these units. We strongly recommend that those with sufficient RAM switch to using the up to date Release 2 units, even if running 1.3. This avoids you having to change programs later on should you choose to switch over or add Workbench 2 features. To configure HSPascal to use the new units from floppy disk, simply use Workbench to drag the HSPascal.prefs and Pascal.cfg icons from Units Disk 2 into your HSPascal drawer, replacing the existing ones. To install HighSpeed Pascal on hard disk with the Workbench 2 units, follow page 10 of the User Manual except that instead of dragging ALL icons from the Units Disk into your HSPascal drawer, drag all the icons EXCEPT Pascal.lib and the Units drawer. Then drag all of the Units Disk 2 icons across (replacing the old preferences files and installing the units) and continue with the installation procedure. The Units Disks ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ The disks now have a slightly differently layout. Instead of 'interface' files, complete source for each Amiga unit is located in the Units drawer so you can now compile them as required. The default Pascal.lib contains each unit plus the Turbo Pascal compatible ones in a compiled form (also supplied). WARNING: Altering unit source files is not recommended as they will most certainly change in future versions! There are a number of new functions and procedures in the Amiga unit although some are for use with Workbench 2 only. Please refer to the source and ROM Kernel Manuals for details. The Graphics and Intuition units automatically include Graphics_2 and Intuition_2 so your program should never 'use' these extra units directly. For 2.0 they contain the unit procedures (and some Intuition compatibility definitions) whilst the 1.3 versions are empty. To compile them you must Make or Build All a program which 'uses' Graphics or Intuition since these units cannot be compiled separately. The Extras drawer on the Units Disk contains ARP and ReqTools library units and the new FileRequest example. These and the 2.0 IFFParse (originally supplied with 1.00) and Rexx units are for use with both Workbench 1.3 and 2.0 although some require other 2.0 units. We suggest that you use the Extras drawer for any additional third-party units. Conventions ŻŻŻŻŻŻŻŻŻŻŻ The conventions used by the Amiga units have changed slightly to bring them even closer to the standard Commodore definitions. Unless you already have programs using the units, these changes will make little difference to you although you should be aware of issues such as sign extension of numbers and C string usage. Types Unsigned types - the unsigned Byte and Word types are used instead of ShortInt and Integer where appropriate. This can cause subtle problems in existing code where a signed variable is used to hold what is now an unsigned value. Always check that you are using the correct type of variable in such cases, e.g. the im_Code field of an IntuiMessage is a Word, not an Integer. Unsigned Long type - although the compiler does not support a true 32-bit unsigned integer type at present, the Exec type 'Long' is used to indicate these. This is mainly used for bit flags which are not affected by signed/unsigned distinctions but you should be careful when comparing Long values. New type names - a number of extra Commodore type names have been added. The most common ones are BPTR in the AmigaDOS unit (used for file handles etc.), STRPTR in Exec for C strings (see below) and PLANEPTR in Graphics. Pointer types - the system units now define 'p' pointer types for all 't' types, not only the ones which they themselves use (page 142, Technical Reference Manual). It is no longer necessary to place these in your own programs. Miscellaneous Variant record field names - some names have been changed to match the preferred C definitions. Strings - contrary to page 143 of the User Manual, the only operating system functions which take ordinary Pascal strings are OpenLibrary, OpenDevice and OpenResource. All other functions which require a string now expect a STRPTR which is a pointer to a null-terminated string. A discussion on strings can be found at the end of this file. Delay procedure - Delay in the AmigaDOS unit now has a trailing underscore in its name to avoid confusion with the built in System unit procedure. System.Delay works in 1/1000ths of seconds whilst AmigaDOS.Delay_ uses 1/50ths. CIA unit - all functions and procedures in this unit now take a pointer to an open CIA resource as their first parameter. This is identical to the C behaviour and replaces the now obsolete CiaBase variable. 2.0 Units ŻŻŻŻŻŻŻŻŻ With Release 2 of the operating system, most libraries, devices and resources have undergone major changes. There are new functions, procedures and types in the 2.0 units for things like object oriented gadgets, public screens, graphics overscan support, AmigaDOS pattern matching, file notification, record locking, argument parsing, Workbench AppMessages and more. Some 1.3 procedures (including AmigaDOS Close and CloseScreen in Intuition) are now functions which return values. To compile existing Pascal programs which use these, you should add dummy variable assignments such as junk := Close(file). 'Junk' should be Boolean in this case. Take care to use the correct type of variable otherwise a range check error may occur. The supplied demos and units use the WORKBENCH_2 conditional to determine which version of the units is being used so that they can be compiled with both. Listed below are the additional units supplied as part of the 2.0 set. Note that the Workbench and Keymap units, which contain only type definitions in the 1.3 version, are now libraries. New Units ASL - the Application Support Library which provides standard 2.0 file and font requesters as used by the 2.0 HSPascal editor. An example of its use can be found in the FileRequest example in the Extras drawer. BattClock - a resource which provides access to the Amiga's battery backed clock. BattMem - not intended for general use, the BattMem unit is used to read and write the small amount of battery backed RAM present on some machines. Commodities - this is the library which enables 'commodities' programs such as screen blankers, hotkeys etc. to be written. These change system behaviour by intercepting or translating certain input events. In addition to the library routines, the Commodities unit contains a number of support functions. GadTools - the 2.0 gadget toolkit library allows you to create and manipulate all the 'new look' 3D gadget types used by the Prefs editors and HSPascal. Menu creation and layout functions are also provided. GadTools is the easiest way to give a 2.0 look and feel to your programs. RamDrive - the device which handles recoverable RAM disks. Rexx - also usable from 1.3, this unit provides a Pascal interface to ARexx, the standard Amiga macro language for InterProcess Communication. The rexxsyslib.library provides most of the ARexx support functions, others form part of the unit. Utility - contains a collection of useful library functions including 'tag' and 'hook' manipulation (used by many 2.0 libraries for attribute/value lists and program callbacks), and various string and arithmetic functions. The FileRequest example shows how to use tags in Pascal. C Strings ŻŻŻŻŻŻŻŻŻ Many system libraries and structures use null-terminated strings (called C strings from now on). Although mentioned briefly in the manual (page 143, User Manual), this section is intended to assist you in working with C strings from Pascal programs. C strings are usually referenced as a pointer to the first character in the string (although a pointer to any string character also yields a valid string). With the exception of OpenLibrary, OpenDevice and OpenResource which use regular Pascal strings, all system functions which take strings use the Exec STRPTR type, although record types generally use pByte. The CString and pCString types (page 143, Technical Reference Manual) are no longer present. It is much easier and more flexible to instead use the Pascal String type for both string formats. The Pascal units retain the Amiga's use of C strings for maximum efficiency, to avoid limiting strings to 255 characters, and to make it easy to use strings directly from system structures. However, this does mean that string conversions are often required when mixing Pascal and operating system functions. One notable exception to this is the Text_ procedure in Graphics which takes both a pointer and a length. Text_(@s[1], Ord[s[0]]) is the most efficient method of passing a Pascal string to this procedure. There are a many different approaches to this problem, the one you select will depend upon your requirements and what you feel comfortable with. Some techniques which we have found useful are adding #0 to strings, conversion by copying, single string conversion, 'dual format' strings and use of C string functions. More detailed explanations of these methods follow. Don't be put off if some seem rather complicated; they are all doing much the same thing so you could use any method. Adding #0 To Strings By far the simplest way of creating a C string is to simply add a zero byte to the end of a Pascal string. The address of element 1 can then be used as a STRPTR. Two examples of this are: s := 'tempfile'#0; if DeleteFile(@s[1]) then... win_name := win_name + #0; nw.Title := @win_name[1]; Conversion By Copying The Exec unit PasToC and CToPas procedures take a Pascal String and a C string variable (or vice-versa for CToPas) and copy the contents of first into the second. Note that these C strings are VAR parameters, not pointers. PtrToPas in the Amiga unit is a version of CToPas which takes a STRPTR, ideal for copying strings from system structures. PasToC('Hello', cstr); {cstr is a CString var} PasToC(s, cstr); {s is a String variable} CToPas(node^.ln_Name^, s); {note the second ^} s := PtrToPas(node^.ln_Name); {different syntax} Single String Conversion A slight variation on the above which requires only one String variable, changing its representation from Pascal to C format. This saves you having an extra variable although you do lose the original Pascal representation. StringToC in the Amiga unit works in this way, returning a STRPTR to the first character for convenience. Example: s := 'tempfile'; l := Lock(StringToC(s), ACCESS_READ); fh := Open(@s, MODE_OLDFILE); {can be re-used} Dual Format Strings Possibly the neatest and most efficient method, this uses some tricks to make a String variable suitable for BOTH formats. NullTerm and MakeString in FileRequest.pas show how this is done. The only pitfall is that you must use these functions each time the string is changed. C String Functions It is sometimes easier to avoid converting C strings at all and instead work with them in their existing form. If you already know C or assembly language, you may like to try implementing some of the basic C string manipulation functions yourself. An example of strncpy() can be found in FileRequest.pas.