Amiga ISO Collection/AmigaUtilCD2.iso/Programming/Pascal/HISOFTPASCAL2,0-2.DMS/in.adf/ReadMe

Text File | 1992-05-26 | 11.7 KB | 308 lines

    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.