afb@j.cc.purdue.edu (Matthew Bradburn) (12/11/87)
# This is a shell archive.
# Remove everything above and including the cut line.
# Then run the rest of the file through sh.
#----cut here-----cut here-----cut here-----cut here----#
#!/bin/sh
# shar: Shell Archiver
# Run the following text with /bin/sh to create:
# arp31.docs
# This archive created: Thu Dec 10 15:34:46 1987
# By: Matthew Bradburn (Purdue University)
cat << \SHAR_EOF > arp31.docs
^L
TABLE OF CONTENTS (not in order)
arp.doc/Printf
arp.doc/FPrintf
arp.doc/Puts
arp.doc/ReadLine
arp.doc/GADS
arp.doc/Atol
arp.doc/EscapeString
arp.doc/CheckAbort
arp.doc/CheckBreak
arp.doc/Getenv
arp.doc/Setenv
arp.doc/FileRequest
arp.doc/CloseWindowSafely
arp.doc/CreatePort
arp.doc/DeletePort
arp.doc/SendPacket
arp.doc/InitStdPacket
arp.doc/PathName
arp.doc/Assign
arp.doc/DosAllocMem
arp.doc/DosFreeMem
arp.doc/BtoCStr
arp.doc/CtoBStr
arp.doc/GetDevInfo
arp.doc/FreeTaskResources
arp.doc/ArpExit
arp.doc/ArpAlloc
arp.doc/ArpAllocMem
arp.doc/ArpOpen
arp.doc/ArpDupLock
arp.doc/ArpLock
arp.doc/FindProcess
arp.doc/GetDataSegment
arp.doc/PatternMatch
arp.doc/FindFirst
arp.doc/FindNext
arp.doc/FreeAnchorChain
^Larp.doc/DosAllocMem (V31)
NAME DosAllocMem -- AmigaDOS compatible memory allocator
SYNOPSIS
memBlock = DosAllocMem( size_in_bytes )
d0 d0
FUNCTION
This function returns a memory block of the size requested, or
NULL if the allocation failed. The memory will satisfy the
requirements of MEMF_PUBLIC | MEMF_CLEAR.
As expected by AmigaDOS, the total size of the memory block is
stored at (memblock - 4), so the actual memory allocated will
always be four bytes larger than size_in_bytes.
INPUTS
size_in_bytes - the size of the desired block in bytes.
RESULT
memBlock - a pointer to the allocated free block. This block
will be longword aligned, and the total size of the
block is stored at (memblock - 4). If the allocation
failed, memBlock will return zero.
ADDITIONAL CONSIDERATIONS
The value returned by DosAllocMem is a real pointer. If you
need a BPTR, you must convert this value yourself.
BUGS
None known.
SEE ALSO
DosFreeMem()
AUTHOR: SDB
REVISED:
^Larp.doc/DosFreeMem (V31)
NAME
DosFreeMem -- AmigaDOS compatible memory freer.
SYNOPSIS
DosFreeMem( memBlock )
A1
FUNCTION
This function frees a memory block which was allocated using
DosAllocMem or was allocated by AmigaDOS.
INPUTS
memBlock -- the pointer to the memblock returned by DosAllocMem.
This pointer may also be NULL, in which case no
memory will be freed.
ADDITIONAL CONSIDERATIONS
memBlock is not a BPTR - if you are passing a value obtained
from AmigaDOS, make sure you convert it from a BPTR to a real
pointer first!
RESULT
None.
BUGS
None known.
SEE ALSO
DosAllocMem()
AUTHOR: SDB
REVISED:
^Larp.doc/Printf (V31)
NAME
Printf -- print formatted data on current output.
SYNOPSIS
count = Printf("String", *args)
d0 A0 A1
FUNCTION
Print formatted data on current output stream. This function
is implemented as FPrintf( Output(), "String", *args), please
see that page for more information.
INPUTS
See FPrintf entry for "String" *args.
RESULT
See FPrintf entry.
BUGS
None known.
SEE ALSO
FPrintf, Puts.
AUTHOR: SDB
REVISED:
^Larp.doc/FPrinff (V31)
NAME
FPrintf -- print formatted data on file.
SYNOPSIS
count = FPrintf(File, "String", *args)
D0 A0 A1
FUNCTION
This function performs 'standard' C-style formatting of data on
the specified output file. It uses the exec function
RawDoFmt() to do the actual formatting of the data. The %
types supported by this function are quite standard, see any C
reference for details.
INPUTS
File - A valid AmigaDOS output file handle, such as returned
by Open() or Output().
"String" - pointer to a C-style format string.
*args - Pointer to start of argument stream.
RESULT
count - if all goes well, the total count of characters
actually written will be returned. If an error occured,
this function will return -1. If this function is
passed a NULL output filehandle, this function will
return zero.
ADDITIONAL CONSIDERATIONS
If your compiler uses a default int size of 32 bits (i.e., Lattice),
you *must* specify %lx or %ld, for example, instead of %d
or %x, since the compilers will promote all ints to longs
before passing them to this function.
Note also that this function very likely has a different idea
of stdout then the support libraries for your compiler.
BUGS
None known.
SEE ALSO
Printf, Puts, exec.library/RawDoFmt, C language reference on printf.
AUTHOR: SDB
REVISED: cdh 26-sep-87 Use ArpBase not DosBase for call
^Larp.doc/CreatePort (V31)
NAME
CreatePort -- Create a message port.
SYNOPSIS
msgport = CreatePort("Name", priority)
d0 A0, D0 (0:8)
FUNCTION
Creates a message port with the given name and priority. This
function is equivalent to that in amiga.lib, but is reentrant, and
may be called by assembly code.
INPUTS
Name - pointer to a null terminated character string, or NULL. If NULL,
this function will not attach the port to the system msgport
list (it will be private to the caller).
priority -- the priority of this msgport (-128..127).
RESULT
Pointer to an initialized message port, or NULL, if port could not
be allocated. If Name was non-null, then the port will have been
added to the system's msgport list.
BUGS
None known.
SEE ALSO
DeletePort
AUTHOR: SDB
REVISED:
^Larp.doc/DeletePort (V31)
NAME
DeletePort -- Deletes a message port.
SYNOPSIS
DeletePort(port)
A1
FUNCTION
Removes a message port.
INPUTS
port - pointer to a message port - may be private or public.
port may also be NULL, in which case this function does nothing.
RESULT
None.
ADDITIONAL CONSIDERATIONS
Functionally equivalent to amiga.libs DeletePort, although the Amiga
version does some extra stuff which is not done here, largely
because it does not appear needed.
BUGS
None known.
SEE ALSO
CreatePort
AUTHOR: SDB
REVISED:
^Larp.doc/InitStdPacket (V31)
NAME
InitStdPacket -- Initialize a standard packet structure.
SYNOPSIS
InitStdPacket(Action, Args, Packet, replyport)
D0 A0 A1 A2
FUNCTION
This function performs the initialization required for a packet
before it is posted to AmigaDOS.
INPUTS
PacketType -- The type (action) of packet you need.
Packet -- Address of the start of the standard packet you wish
initialized. NOTE! - this is the start of the message
portion of the packet, NOT the actual packet itself.
ReplyPort -- The replyport for this packet.
Args -- pointer to an array of 7 longwords representing the
argument values you wish to send to AmigaDOS. If this
is NULL, the packet arguments will be cleared.
RESULT
The StdPacket is initialized according to your requests.
ADDITIONAL CONSIDERATIONS
Note that AmigaDOS destroys the value of the replyport in the
packet structure each time it is posted, therefore, you must
preserve a local copy of this pointer, and reinitialize it each time.
BUGS
None known.
SEE ALSO
SendPacket
AUTHOR: SDB (Version 8)
REVISED:
^Larp.doc/SendPacket (V31)
NAME
SendPacket -- Send a packet to DOS.
SYNOPSIS xxxxxx
Result1 = SendPacket( Action, Args, Handler, Result)
d0 d0 a0 a1 a2
xxxxxx
FUNCTION
Sends an AmigaDOS packet to a handler. This function will Wait(),
if necessary, until the Handler returns the packet. It cannot
therefore be used for asynchronous I/O. This function uses the
processes message port, and it will call the pr_PktWait function
if this is installed.
INPUTS
Action -- the action you wish this packet to cause.
Args -- Pointer to an array of seven long words which specify the
arguments to send with the packet. This may be NULL, in which
case the arguments will be set to zero.
Handler -- The address of the msgport of the handler you wish to
receive this packet.
Result -- Pointer to an array of two long words in which the
result1 and result2 of the returned packet will be
placed. This may be NULL.
RESULT
This function returns the result1 field of the returned packet.
ADDITIONAL CONSIDERATIONS
Providing a higher level language environment for a user installed
PktWait function is an exercise left to those who require it.
For use in assembly language, d0 will hold the result1 field,
and d1 will hold the result2 field.
DIAGNOSTICS
See the return values for the packets which you post. Note that
other processes (dos handler processes) are also using the process
message port. If this function gets a packet other than the one it
posted, it will GURU out.
BUGS
None known.
SEE ALSO
InitStdPacket
Author: SDB
Revised: V15.5 -- Uses process message port, which is vastly superior
to the way we were doing this originally. In particular, this
allows us to return res1 and res2 instead of the former returns.
Many thanks to whawes for this suggestion. (SDB)
Revised: Result array arg removed
^Larp.doc/EscapeString (V31)
NAME
EscapeString -- convert escape characters in string.
SYNOPSIS
NewLength = EscapeString( "String" )
D0 A0
FUNCTION
This function scans the string, replacing all escaped characters
with the correct byte value. This function uses the value for ESCAPE
set in ESCChar in ArpBase, which is maintained elsewhere; this value
defaults to the BCPL '*' (RSN), or may be the normal '\'.
This function currently recognizes the following special characters:
N - newline
T - horizontal tab
V - vertical tab
B - backspace
R - return
F - formfeed
E - escape (ascii 27 decimal)
Xnn - character representd by hex value nn.
The above may be either upper or lower case. If this function
finds an escaped character which is not one of the above, it will
return the character value (i.e. '\A' will be replaced by the single
character 'A'. The sequence '\\' is replaced by the single
character '\', and so on.)
For sending hexcodes, the \x argument may be followed by either one
or two hex digits, in either upper or lower case.
INPUTS
string - pointer to a null terminated ASCII string.
RESULT
A new string, starting at the same memory location, but with the
escaped characters (if any) changed to their actual byte values.
This string will be null terminated.
NewCount -- The new length of the string.
ADDITIONAL NOTES:
For easy use in assembly language parsers, this function will
return with the A0 register unchanged.
BUGS
Routine uses the region of memory pointed to by A0 as a work area,
so if you wish to retain a pristine copy of the string, copy it first.
SEE ALSO
GADS
AUTHOR: SDB
REVISED: cdh 16-sep-87 Use ESCchar in ArpBase, rather than wild flags
^Larp.doc/PathName (V31)
NAME
PathName - Find complete pathname of file/directory.
SYNOPSIS
Length = PathName(Lock, Destination, NumberNames)
D0 D0 A0 D1
FUNCTION
This function builds a path name which completely describes the
path from the root of the filing system to the file on which the
Lock has been obtained.
The name returned is of the form:
Volume:Dir1/Dir2/Dir3/.../Name\x00
INPUTS
Lock -- Thisis a lock on the file or directory obtained from Lock()
or DupLock(), or some such function.
Destination -- This is the area of memory to place the filename in.
NumberNames -- This is the number of names that can be placed in
the destination area. You should reserve 31 bytes
for each pathname component. The minimum buffer
size would be 32 bytes, which would allow room for
one name.
RESULT
The resulting pathname will be placed in Destination.
If everything goes well, then you get the total length of the
pathname, in characters accumulated. If there is a problem (either
the buffer is too small, or there was a disk error), you will get a
zero.
BUGS
None known.
SEE ALSO
Author: SDB
^Larp.doc/ReadLine (V31)
NAME
ReadLine -- Get a line from current input. (stdin)
SYNOPSIS
Count = ReadLine("Address")
d0 A0
FUNCTION
This function reads a line of up to MaxInputBuf characters from
stdin. You must have a buffer available of this size, or you
run the risk of overwriting innocent memory. MaxInputBuf is
defined in arpbase.[h|i].
This function does no editing or echoing of the command line,
although it does guarantee the returned string is null terminated.
INPUTS
Address - Pointer to a 256 byte buffer to store the input
string in.
RESULT
Count - The actual count of the characters returned.
Address will contain a null terminated string of Count characters.
BUGS
None known - there may be problems using this function on other
than a CON: window (i.e., a file, or RAW:), but
nothing definite is known at this time.
ADDITIONAL NOTES:
For the convenience of assembly language programs, A0 is guaranteed
to contain the same value on exit as it did on entry.
SEE ALSO
GADS, EscapeString.
Author: SDB
Revised: VERSION 8, removed SIZE argument, returns NULL if no input handle.
^Larp.doc/Atol (V31)
NAME
Atol -- Ascii string to long int.
SYNOPSIS
intval = Atol("string")
d0 a0
FUNCTION
Convert "string" to a long integer. This function will skip
leading whitespace.
This function returns an error if a non-whitespace non-digit
is encountered during processing.
INPUTS
string - pointer ascii string, which may be null terminated
or whitespace terminated. The digits may have
leading whitespace.
RESULT
intval -- a long integer value.
If an non-numeric is encountered during processing
other than surrounding whitespace or null
terminators), this function will return with the Z
flag SET, and the offending character value in d0.
If the Z flag is clear, then all characters
encountered were either whitespace or digits.
ADDITIONAL CONSIDERATIONS
This function is callable by higher level languages,
but the glue routine must take the responsibility
for detecting the error returns, and informing the
caller in a fashion appropriate to the language in use.
BUGS
Values which cannot be represented as a 32bit integer will
not cause an error.
Author: SDB
^Larp.doc/Puts (V31)
NAME
Puts -- Print string with newline on stdout.
SYNOPSIS
BOOL = Puts("string")
d0 a1
FUNCTION
Writes a string to stdout, and then writes a terminating newline.
This is currently implemented as Printf("%s\n", string).
INPUTS
string - pointer to ascii string. (null terminated)
String may be null, in which case a newline only will
be displayed.
RESULT
See FPrintf page for more information - note that this
function always trys to write a newline.
BUGS
None known.
SEE ALSO
Printf, FPrintf.
Author: SDB
Revised: String is now in A1 to allow a more efficient implementation.
THIS IS INCOMPATIBLE WITH EARLIER VERSION OF THE LIBARARY.
SDB.
^Larp.doc/GetDevInfo (V31)
NAME
GetDevInfo -- traverse through DevInfo device list
Traverse through Devinfo list
Call with A2 = current position in Devinfo list (or NULL)
Returns D0 ( and A2 ) = next entry in Devinfo list (or head)
Also - side effect - ZERO FLAG IS SET ZERO if end of list
Puts -- Print string with newline on stdout.
SYNOPSIS
devinfo = GetDevInfo( devinfo | NULL )
d0/A2 A2
FUNCTION
Traverse to next entry in DevInfo device list
If input is NULL, returns head of DevInfo
At end of list, returns NULL.
Side Effect - Zero Flag is NULL return status
INPUTS
devinfo - pointer to current entry in devinfo list.
if NULL, get head of list
RESULT
Next entry of devinfo list is in D0 and A2
If result is NULL, end of list (Zero flag is set)
BUGS
None known.
SEE ALSO
Assign
Author: cdh
Revised: 20-sep-87 cdh Added traversal (originally only got head
of list ).
^Larp.doc/Assign (V31)
NAME
Assign -- Assigns a logical device name
SYNOPSIS
Result = Assign("name:","physical")
D0 ao a1
FUNCTION
This function performs the guts of an AmigaDOS "assign"
function. The arguments are similar to the arguments of the
ADOS program "Assign logicaldev: directory".
INPUTS
"name" -- Name to create a Devinfo assigned name for.
"physical" -- Name of file or directory to get a Lock from.
NOTE - if physical is NULL, remove existing name.
RESULT
A Devinfo entry is created for the requested name. Any prior
assignment for that name is removed.
Result -- an error code return which may be one of:
ASSIGN_OK everything worked this time.
ASSIGN_NODEV "physical" did not represent a valid directory.
ASSIGN_FATAL Something is really rotten somewhere.
ASSIGN_CANCEL Attempt to cancel something (like a
volume) that can't be canceled.
BUGS
None known.
Author: cdh 15-may-87
Revised: SDB Version 8.1, make A6=ArpBase for most ArpLib calls,
Various other minor changes.
20-sep-87 cdh Added null input calls "DeleteDevice"
^Larp.doc/BtoCStr (V31)
NAME
BtoCStr -- Copy a BSTR to a C null terminated string
SYNOPSIS
Count = BtoCStr("CString", BSTR, MaxLength)
d0 A0 D0 D1
FUNCTION
This function copies a BSTR into a null terminated string.
The BCPL string is passed as an unconverted icky BCPL ptr.
INPUTS
CString - Pointer to a buffer area for the resulting string.
BSTR - BPTR to the BSTR to convert.
MaxLength - Maximum number of characters in buffer (not
including NULL terminator).
RESULT
Count -- Actual number of characters copied.
A0 has START of C string for assembly convenience.
ADDITIONAL NOTES:
This function does NOT require A6 to be ArpBase. This info
if for internal (library) use only! Within the Arp library
you can bsr CtoBStr without setting A6 = ArpBase.
Author: cdh 15-May-87
Revised:
^Larp.doc/CtoBStr (V31)
NAME
CtoBStr -- Copy a C null terminated string to a BSTR
SYNOPSIS
Count = CtoBStr("CString", BSTR, MaxLength)
d0 A0 D0 D1
FUNCTION
This function copies a null terminated string into a BCPL
string. The BCPL string is passed as an unconverted icky
pointer.
INPUTS
CString - pointer to the string to convert.
BSTR - BPTR to the destination string.
MaxLength -- Number of characters available in BSTR (not
including initial count byte.)
RESULT
Count -- actual number of characters transferred.
A0 and A1 are zapped.
ADDITIONAL NOTES:
This function does NOT require A6 to be ArpBase. This info
is for internal (library) use only! Within the Arp library
you can bsr CtoBStr without setting A6 = ArpBase.
Author: cdh 15-May-87
Revised:
^Larp.doc/FindProcess (V31)
NAME
FindProcess -- Find a process given a CLI task number.
SYNOPSIS
Process = FindProcess(tasknum)
d0 d0
FUNCTION
This function returns the pointer to the process structure
associated with tasknum. This is a pointer to the start of
the process structure, usable with EXEC calls, and not the
process value returned by DOS calls.
INPUTS
The CLI task number for the process, or special case ZERO,
which returns the total number of process slots.
NOTE: YOU MUST FORBID PRIOR TO CALLING THIS FUNCTION!
This function only makes sense when you are Forbidden, as
otherwise the process may squirt away from you before you
can use the result! Thus this function does NOT Forbid
around a critical section. You have been warned!
RESULT
Process -- a pointer to a Process structure, or NULL. A NULL
return indicates that there is no currently active
process associated with that CLI task number.
( Except if tasknum was Zero )
BUGS
None known.
Author: SDB
Revised:
^Larp.doc/CheckAbort (V31)
NAME
CheckAbort -- Check for control C
SYNOPSIS
BOOL = CheckAbort( *Func() )
d0 A1
FUNCTION
This function checks to see if the user issued a CNTRL-C abort
for this process (either keyboard, or from Break). It can
one of three possible actions.
If CNTRL-C occurred:
If (*)(func)() is NULL, then the CNTRL-C system flag will
be returned.
If (*)(func)() is NOT null, it will be called. If it
returns, you will see the return code from your function.
If CNTRL-C did not occur, you will get a ZERO return, and
(*)(func)() will not be called, even if non-null.
INPUTS
*Func() -- an (optional) function to call if CNTRL-C occured.
NOTE - if Func() is called, the and you "rts" from Func, you will
return to the caller of CheckAbort.
RESULT
Zero if no CNTRL-C.
If *Func() is null, a NON-Zero function return will occurr.
If *Func() is not null, you will see this return value.
BUGS
None known.
Author: SDB
Revised:
^Larp.doc/CheckBreak (V31)
NAME
CheckBreak -- Check for control C/D/E/F
SYNOPSIS
BOOL = CheckAbort( Mask(s), *Func() )
d0 D1 A1
FUNCTION
This function will check to see if the user issued a
CNTRL-C/E/D/F abort (from keyboard or Break program), and will
take one of three possible actions.
If the BREAK occurred:
If *Func() is null, then the Actual Mask will be returned.
If *Func() is NOT null, it will be called, and you will
see the return code from that function.
If a BREAK did not occur, you will get a ZERO (false)
return, and *Func() will not be called, even if non-null.
INPUTS
Mask(s) -- One (or more) of SIGBREAKF_CTRL_C/D/E/F masks.
*Func() -- an (optional) function to call if the BREAK occured.
RESULT
Zero if no Break
If *Func() is null, you will get the masks that caused
this break.
If *Func() is not null, you will see your return value.
ADDITIONAL:
For this function, we guarantee all registers preserved,
except for D0, which will hold the masks.
For CheckAbort, all registers will be preserved, except
for D0/D1.
BUGS
None known.
Author: SDB
Revised: cdh V25 return ***BREAK string in A1, return is same level
as call (return address overwritten)
^Larp.doc/GADS (V31)
NAME
GADS -- Do standard AmigaDOS command line parsing.
SYNOPSIS
Count = GADS( "line", len, "help" args, "tplate");
d0 a0 d0 a1 a2 a3
FUNCTION
This function performs the standard AmigaDOS style command
line parsing, using the standard AmigaDOS style templates. It
also handles interactive command lines for you.
Interactive command lines occur under AmigaDOS when the user
types a command name followed by a '?' as the first argument.
This program will also perform all the normal AmigaDOS
processing on the command line before the parse. In
particular, this means handling any escape characters that are
found in the line. The method used by AmigaDOS (and in this
function) is to escape quoted commands, but not unquoted
commands. Quotes will be stripped unless escaped.
Note that ArpLib recognizes a more extensive escape vocabulary
than AmigDOS (see EscapeString). Note also that one exception
to the above occurs when a function is passed a null 'tplate'
pointer.
GENERAL DISCUSSION
Programs calling this function present a very different
appearance to the calling program than is presented to the
user of the program.
To the user, it appears as though they have a fair amount of
flexibility in the order in which they type their arguments.
To the calling program, an argument which is specified as
first in the template will ALWAYS occupy that slot, if it
occurs in the users command line, no matter where in the
command line this argument occurs. Here is an example:
FROM/A,TO,OPT/K,FOOBAR/S ( template )
0 1 2 3 ( arg position)
This is how it appears to both the user and the caller:
USER OF PROGRAM TYPES: PROGRAM SEES:
f1 f2 | arg[0] = f1, arg[1] = f2
f1 TO f2 | arg[0] = f1, arg[1] = f2
TO f2 FROM f1 | arg[0] = f1, arg[1] = f2
OPT zip FOOBAR TO f2 FROM f1 | arg[0] = f1, arg[1] = f2
| arg[2] = zip arg[3] = TRUE
If an argument is a string (\A \K or optional), then a pointer
to the string which is the value of that argument is placed
in the args array. If the string is not found, then a NULL
will be placed in the array slot for that argument (although
this might cause an error under certain circumstances - see
below).
If the argument is a SWITCH (\S) then -1L will be placed in
the args slot for that switch, or FALSE, if the switch was
not found on the command line.
Note that this function DOES DO ERROR CHECKING on the
arguments. In particular, this means that if you specify a
template with a required argument (\A), you can count on it
being there, you do not have to check for it's existance, as
this function will return an error to you if it is not present.
There are other conditions which can cause an error to be
returned, see below for more information.
INPUTS
"cmdline" -- pointer to the command line, just as you get it
from DOS.
cmdlen -- length of command line, just as handed to you by
DOS.
argarray -- Pointer to the start of an array of longwords
which will receive the results of the argument
parse. There must be as many longwords in this
array as there are arguments in the template.
There must ALWAYS be at least one element in this array.
You may declare this in C as an array of:
union { char *string; for optional, /a, /k.
long boolean; for /s
}
"tplate" -- Pointer to an AmigaDOS style template. This
function assumes that the template is 'well
formed', i.e., no spaces, tabs, etc., and that it
null terminated. Do NOT end your template
with ':'. It may contain mixed cases.
"xtra help" -- optional extra help string, which may be as
long as you like, and include any type of
characters you desire. The user will see this
string if they type a question mark after they
have already entered interactive processing.
If you don't have any xtra help to supply, then
this should be NULL, and this routine will use
a default help string.
RESULT
COUNT -- The number of arguments found, or -1 if there is an
error in the comand line. This function is fairly
demanding about command line syntax. Here are some
of the things that currently cause an error:
An opening quote without a closing quote. (Note
that the inverse is ok: "OOPS is a mistake, but
OOPS" is ok. This is consistant with the behavior
of AmigaDOS.)
An argument specified as required (\A) was not supplied.
Too many arguments were supplied.
An argument was supplied where a keyword was expected.
A Template word which required an argument (i.e.,
anything except a \S element) was supplied, but no
argument was found.
In interactive mode, no memory for input buffer.
ArgArray -- If COUNT is nonzero, ArgArray contains the results
of the parse. The actual value of the arguments
will be placed in the position of the ArgArray
corresponding to their descriptor in the
template. If the user supplied a quoted string,
the string will be scanned for escape characters,
and the appropriate substitutions made.
If COUNT is ZERO, arg array will contain the same
values as those it had at entry to this function.
This allows you to preinitialize the arg array.
If COUNT is -1, then ArgArray is in an unknown
state. The only option open to you at this point
is to issue an error message and scram.
WARNING/ADDITIONAL CONSIDERATIONS
Note that the initial commandline pointer may not be valid
after a call to this function, due to the interactive command
line feature. Use only the argarray values.
BUGS
No error checking is performed on the actual syntax of the
template. This routine assumes you did it right.
Could alter the original cmdline area, and will, except in
the case of interactive input.
Does not recoginze the ';' CLI comment character on interactive
input.
ADDITIONAL NOTES:
If "template" is null (i.e., as might be used by Echo, for
example), interactive command line processing will take
place, and arg[0] will contain a pointer to the processed
string. Quotes will be stripped, if found (note that
unmatched quotes will return an error.). Currently, in the
case of a NULL template, the single argument will be escaped
whether it is quoted or not. This should be ok, since only ECHO
currently uses this facility.
Author: SDB
Revised: Version 16
Bug fix:
Templates with 'holes' such as arg1,arg2,,arg3
are now correctly parsed.
New Feature:
If a command line error occurs which is detectable
by this program, the first element of the argument
array will contain a pointer to a null terminated
string which may by Puts() to inform the user of
an error. Comments on the error messages are welcome.
Please use this feature if you can, to avoid the
"Bad Args for Glork" syndrome.
Clarification:
GADS() will only detect a missing \A argument if
there is NOT a null command line. So if you have
a template with a \A argument, if the return from GADS
is not 0 (NULL command line), then you can count on
the \a argument being there. A simple test:
if (GADS() <= 0)
ERROR
will suffice.
Final Fixes (I hope):
Use toupper for case change
Will treat an unquoted ';' as EOL.
^Larp.doc/GetDataSegment (V31)
NAME
GetDataSegment -- Get a data segment + ptr for resident program.
SYNOPSIS
memBase = GetDataSegment(base, size)
d0 a0 d0
FUNCTION
This function provides a method where programs which
ordinarily could not be made resident will work as resident
code modules.
Resident code modules have only one copy of the program text
in memory at one time, no matter how many instances of that
program may exist in the system. Ordinarily, programs must be
written in a special manner to allow this to occur. However,
this function should allow most programs to run as resident software.
The only restriction on a program which intends to be resident
is that it's data must reside in a single block of memory, no
greater than 64k in size, and it must access it's data by
offsets from a base register (which will point in the middle
of this area, of course).
INPUTS
base -- pointer to the base of the programs data
size -- size of data region in bytes.
RESULT
Memory will be allocated for the new data area, the original
data will be copied to this location, and a pointer to the
middle of this region will be returned.
ADDTIONAL CONSIDERATIONS
Many, but note that for Manx users, they will need special
startup code, as well as a new version of geta4(). They
should be extremely careful to link only with libraries that
use the same code model. Exiting should be done with care,
since the data region is automatically deallocated when ArpLib
is closed.
Note also that any additional initialization of the data area
must be carried out before this function is called.
BUGS
None known.
Author: SDB (V11)
Revision: cdh v26 save bytes use CALLEXE
^Larp.doc/GetEnv (V31)
NAME
GetEnv -- Get the value of an environment variable
SYNOPSIS
strptr = Getenv("string", buffer, size)
d0 A0 A1 d0
FUNCTION
This function provides an environment variable mechanism
compatible with MANX. Note that this call is more efficient
than using the manx getenv() function call when arplibrary is
installed.
INPUTS
string -- pointer to an environment variable name.
buffer -- a user allocated area which will be used to store
the value associated with the environment variable.
This may be NULL.
size -- size of buffer region in bytes.
RESULT
If found, a pointer to the start of the value string for that
variable will be returned.
If buffer is non-null, then as much of the value string as
allowed by size will be copied into the user buffer.
ADDTIONAL CONSIDERATIONS
MANX was the first to implement environment variables on the
Amiga. As a result, we are trying to be compatible with their
implementation. Note that this function is NOT equivalent to
MANX getenv() call, but can easily be constructed using this
this function. Note also that all calls by MANX will be handled
by arplibrary when it is installed.
You would be wise to run as Forbidden all code which examines the
environment space of the arp.library (for example, using the
return value of this function). As an example, the following code
performs identically to the manx getenv() function:
char getenv(variable)
char *variable;
{
char *temp;
static char *buffer;
free(buffer); /* Free memory from last call */
Forbid();
temp = Getenv(name, 0L, 0L);
if (!temp)
Permit(), return(0);
buffer = malloc(strlen(temp));
strcpy(buffer, temp);
Permit();
return (buffer);
}
BUGS
If size is not large enough, the complete value of that
environment variable will not be copied to the user buffer.
Author: SDB (V12)
Revision:
^Larp.doc/SetEnv (V31)
NAME
Setenv -- Set the value of an environment variable
SYNOPSIS
BOOL = Setenv("string", buffer)
d0 A0 A1
FUNCTION
This function provides an environment variable mechanism
compatible with MANX. Note that this call is more efficient
than using the manx setenv() function call when arplibrary is
installed.
INPUTS
string -- pointer to an environment variable name.
buffer -- a user allocated area which will contains the values
to be associated with this environment variabnle.
RESULT
If the value was succesfully established, a TRUE result will
be returned, otherwise, a FALSE value will be returned.
ADDTIONAL CONSIDERATIONS
MANX was the first to implement environment variables on the
Amiga. As a result, we are trying to be compatible with their
implementation.
BUGS
None known.
Author: SDB (V12)
Revision:
^Larp.doc/CompareLock (V31)
NAME
CompareLock -- Compares two filesystem Locks to see if they
belong to the same object.
SYNOPSIS
Result = CompareLock( Lock1, Lock2 )
D0/Z flag D0 D1
FUNCTION
This function may be used to determine if two file Locks obtained
with the DOS Lock() function belong to the same file/object.
Using this library call allows an application to avoid using
private information; this call may be updated if/when a DOS
Packet ACTION_COMPARE_LOCK is implemented.
INPUTS
D0 and D1 are Locks obtained with DOS Lock()
RESULTS
Return is in D0. If D0 is:
0 - Locks are identical
1 - Locks are on same Volume
2 - Locks are on different Volumes (dn_Task?)
3 - Locks are on different Volumes
Z-Flag reflects return status
BUGS
Caveat, this function now uses information that is considered
"private" to each filehandler; thus, it is possible it will
give an erroneous result if somebody implements a funny
filehandler.
This function was included primarily for the Rename program,
to prevent Rename from creating directory loops that cause the
directory to be lost in BCPL-space.
SEE ALSO
Author: cdh (V19)
Revision:
^Larp.doc/PatternMatch (V31)
NAME
PatternMatch - perform a wildcard match on a string
SYNOPSIS
result = PatternMatch(pat,str)
D0 A0 A1
FUNCTION
This function compares a string to the given pattern and determines
if it is a valid match. If so it returns a true result.
The pattern must be constructed with special preparsed tokens and
supports the following patterns:
(p1|p2|p3) One of the patterns p1, p2 or p3
? Any single character
#<pat> Pattern repeated 0 or more times
[class] Character class
[^class] Negated character class
{pat} Structure tag for replacement
* 0 or more occurances of any character
INPUTS
char *pat The pattern string to match against
char *str The string to be matched
RESULT
result - a boolean value indicating success/failure. The condition
codes are guarenteed to reflect the status of the result
BUGS
None known.
SEE ALSO
Author: JAT
^Larp.doc/FindFirst (V31)
NAME
FindFirst -- Search for multilevel pattern match
SYNOPSIS
rc = FindFirst(pat, chain, info)
d0 D0 A0 A1
xxxx ( Removed V22 )
FUNCTION
This function locates the first match for a pattern
INPUTS
char *pat - pattern to search for
struct Anchor **chain - pointer to file chain
struct FileInfoBlock *info - pointer to file info buffer
RESULT
long rc - 0 for success, non-zero for any error
BUGS
None known.
SEE ALSO
FindNext(), MakeAnchor(), FreeAnchorChain()
Author: JAT
cdh 02-Oct-87 Removed info calling arg - now it is in
the anchor base.
^Larp.doc/FindNext (V31)
NAME
FindNext -- Locate next match for a file pattern
SYNOPSIS
rc = FindNext(chain)
d0 A0
FUNCTION
This function locates the next match for a pattern
INPUTS
struct Anchor **chain - pointer to file chain
RESULT
long rc - 0 for success, non-zero for any error
BUGS
None known.
SEE ALSO
Author: JAT
cdh 02-Oct-87 added break checks
^Larp.doc/FreeAnchorChain (V31)
NAME
FreeAnchorChain -- Free an allocated Anchor Chain
SYNOPSIS
FreeAnchorChain(chain)
A0
FUNCTION
This function frees an anchor chain allocated by FindFirst/FindNext
It may be called multiple times without harm
INPUTS
struct Anchor **chain - pointer to file chain
BUGS
None known.
SEE ALSO
FindFirst(), FindNext(), MakeAnchor()
Author: JAT
^Larp.doc/Strcmp (V31)
NAME
Strcmp -- Compare two strings, ignoring case.
SYNOPSIS
result = strcmp(s1, s2)
d0 a0 a1
FUNCTION
returns <0 =0 or >0
AUTHOR:
sdb
^Larp.doc/Strncmp (V31)
NAME
Strncmp -- Compare two strings for n bytes, ignoring case.
SYNOPSIS
result = strcmp(s1, s2, n)
d0 a0 a1 d0
FUNCTION
returns <0 =0 or >0
AUTHOR:
sdb
^Larp.doc/QSort (V31)
FUNCTION
QSort -- Quickly sort whatever you want.
SYNOPSIS
stkerr = QSort( baseptr, region_size, byte_size, user_function)
d0 a0 d0 d1 a1
FUNCTION
QSort is an implementation of Hoares sorting algorithm. It
uses a constant amount of stack no matter what the size of the
file.
INPUTS
baseptr - pointer to the start of a memory region to be sorted
region_size - size of region to be sorted, in number of elements (not bytes!)
byte_size - size of sorted elements, in bytes.
user_function - function to be provided by caller, which compares two
elements from the set to be sorted. QSort will call the user function
like so:
return = user_function(el1, el2)
d0 a0 a1
Your function must return the following in D0:
if (el1 < el2) return < 0
if (el1 > el2) return > 0
if (el1 == el2) return = 0
You must save all registers except a0, a1, d0, d1.
(See below for an example of a C calling sequence)
QSort will also pass A5 to you unchanged. You can use this register
to point to pass information to your comparison routine.
RETURNS
-1 if everything is cool, 0 if there was an internal recursion
stack overflow (not too likely).
EXAMPLE:
Here is an example of a calling sequence from C, which is to sort
an array of pointers to strings:
char **names;
long numEls;
extern Cmp();
if (QSort(names, numELs, 4L, Cmp))
do whatever
else
STACK_ERROR
the Cmp function would look like this:
Cmp()
{
{
#asm
public _geta4
movem.l d2-d3/a4/a6,-(sp) ; save important registers
movem.l a0/a1,-(sp) ; push args
bsr _geta4
bsr _cmp ; call real compare function
addq.l #8,sp ; clean up args
movem.l (sp)+,d2-d3/a4/a6 ; restore registers
#endasm
}
}
The cmp function called by the above is a normal C function, it can
be whatever you like. Here is a sample one:
cmp(s1,s2)
char **s1, **s2;
{
return strcmp(*a, *b);
}
BUGS
None known.
AUTHOR: SDB (V17)
REVISED:
^L(sorry for the skimpy doc on the next few .. out of time! )
NAME
FileRequest -- Get filename from user
SYNOPSIS
retstr = FileRequest( filereqstruct )
D0 A0
FUNCTION
Prompts the user for a filename. See struct FR_struct in arpbase.i,
NOTE
V1.0 of Arp does not support the FR_Flags, FR_Wildfunc,
or FR_MsgFunc entries in the struct, but you MUST allocate these
and pass NULL values if you want to work with V1.1 of arplib!
^L
NAME
CloseWindowSafely -- close a window without GURUing.
SYNOPSIS
CloseWindowSafely( window, morewindows )
A0, A1
FUNCTION
Closes window after removing any messages pending for it in
the window msgport, for use with a shared window. Without
this precaution, you will GURU when there is fast mouse
activity (or multitasking).
The second arguement is NON-ZERO if there is another window
that still is sharing the msgport (ie, the msgport should
remain unfreed). If the second arguement is NULL, the
msgport is freed as well. Most often, the value morewindows
will be an actual windowptr or NULL; the value doesn't really
matter though, it is just a flag
^L
NAME
AddDANode -- add a new entry to a DAList
SYNOPSIS
newnode = AddDANode( NewNode, *DaList, length, ID )
A0 A1 D0 D1
FUNCTION
Adds a node to a DAList. The address of the DAList header
is in A1; A0 points at the buffer that you want copied
as a DANode. If length is ZERO, NewNode is a null-terminated
string; if length != 0, it is the length of the mem to
copy. ID is a sort key, which may be used by your program
either for sorting or for classification; see AddDADevs
and the bitdefs for how they are used for getting device
names.
SEE ALSO- FreeDAList
^L NAME
AddDADevs -- get a private list of devices/assignments/volumes
SYNOPSIS
numentries = AddDADevs( dalist, select )
A0, D0
FUNCTION
Adds devices, volumes, and/or assigned names to a DAlist in
a way that is both safe for multitasking, and easily accessible
for C/assembler programs.
See bitdefs in arpbase.i for selecting which devlist entries
you want, and identifying what each entry is. The returned
list is sorted both by class, and then by alpha-numeric.
SEE ALSO - FreeDAList
^L NAME
FreeDAList -- Free a DosAllocmem (DA) list
SYNOPSIS
FreeDAList ( dalist )
A1
FUNCTION
Frees all DAList nodes from a DA list. Each node is a singly
linked DosAllocMem block, seach for "DA_" in arpbase.i.
NOTE - The dalist arguement is the actual first item of the list,
NOT a pointer to the list-head!
^L
NAME
FindTaskResList -- find a pointer to current task's reslist
SYNOPSIS Finds the Resource List for this task, or NULL
ResList = FindTaskResList()
D0 (A1) ( Zero flag )
FUNCTION
This function searches for the most recently nested ResList
for the current task, if any. If there are no resource lists
for this task, the return pointer points at NULL.
NOTE - This implementation may change. FindTaskResList is normally
not needed as an external callout, as all task tracking is
done automaticly without the application needing to know about
this
BUGS
None known. Will change to work with SyncRun
^Larp.doc/ArpExit (V31)
NAME
ArpExit -- exit immediately, closing arp, freeing resources.
SYNOPSIS
ArpExit( ReturnCode, (Fault) )
d0 d2
FUNCTION
This function will cause a currently running program to
terminate. It will first CloseLibrary(ArpBase), which will
cause all tracked resources to be freed. It will then force
DOS to unload your program, returning the error code to the CLI.
INPUTS
ReturnCode -- The integer value you wish to return. By
convention, 0 means a normal exit.
Fault -- If ReturnCode is non-zero, this value is the ADOS
error code which is used with the "Why" program,
in pr_Result2. ( If ReturnCode is ZERO, pr_Result2
will be set to 0).
RESULT
No results, in fact, no return.
BUGS
None known.
Author: SDB
Revised: cdh 16-sep-87 Add pr_Result2 fault value in D2
cdh 28-sep-87 Frees ResLists before CloseLibrary,
because CloseLibrary Forbids first - nasty
for system performance.
cdh 29-sep-87 Use pr_ReturnAddr rather than DOS Exit(). Hah.
^Larp.doc/CreateTaskResList (V31)
NAME
CreateTaskResList -- Create a new nested ResList for this task
SYNOPSIS
ResList = CreateTaskResList()
D0 / Z Flag
FUNCTION
Create a new Resource list for this task, and insert it at the
HEAD of the ResourceArray list.
You do not normally need to use CreateTaskResList, because the
functions which insert tracked items into the task reslist
will automaticly create a reslist if one did not exist before.
This function may be used to explictly create a nested ResList
for this task; all resources allocated after CreateTaskReslist
will be stored in the new ResList until you call FreeTaskResList.
This would allow you, for instance, to call CreateTaskResList at
the start of a function, and FreeTaskResList at the end of the
function, and any resources tracked in the interum would be
freed; but all other tracked resources for the task would
remain tracked.
All Task reslists will also be automaticly freed when you call
BUGS
None known. Current implementation will change slightly when
SyncRun is added to arp.library
Author - cdh V18
^Larp.doc/ArpAllocMem (V31)
NAME
ArpAllocMem -- Allocate and track memory.
SYNOPSIS
MemPtr = ArpAlloc( size, reqs )
d0 (a1) D0 / D1
FUNCTION
This function is identical to the Exec AllocMem call, but will
track memory resources for you.
When you CloseLibrary(ArpBase), any memory allocated with this
function will be freed, which provides a simpler means of
termination than is ordinarily found.
You may make multiple calls to this routine -- all memory
resources will be tracked. Note also that this function
requires you to specify the type of memory, so that you may
also allocate and track CHIP memory using this function.
INPUTS
Same args as Exec AllocMem request, size / reqs
RESULT
MemPtr -- pointer to the memory requested, same as Exec AllocMem
return. If this is NON-ZERO, the memory allocation
succeeded.
Tracker -- same as all the tracking calls, register A1 contains
the pointer to the TRACKER. See ArpAlloc, GetTracker,
CreateTaskReslist,FreeTaskReslist.
WARNING
Do NOT call FreeMem to free the memory from this allocation!
If you want to free this allocation before terminating the task,
or before calling FreeTaskReslist, you MUST use the TRACKER pointer
and use FreeTrackedItem.
If you want to manage your own memory, use the exec calls directly.
BUGS
None known.
SEE ALSO
ArpAlloc(), GetTracker(), FreeTaskResList()
AUTHOR: SDB (V8.4)
Revised: cdh V23 converted to AllocMem rather than AllocEntry
^Larp.doc/ArpOpen (V31)
NAME
ArpOpen -- Open a file and track it.
SYNOPSIS
FileHandle = ArpOpen("name", accessmode)
d0 d1 d2
FUNCTION
This function is equivalent to the AmigaDOS Open(), except
that this function will remember that the file is open when
you do a CloseLibrary(ArpBase) and close it for you.
This is part of the Resource tracking of ArpLib, which also
tracks memory allocations and Locks.
INPUTS
name - pointer to a null terminated string.
accessmode -- pointer to a valid AmigaDOS access mode.
RESULT
A BPTR to a filehandle, or NULL, if an error occurred.
BUGS
None known.
SEE ALSO
ArpAllocEntry(), ArpAlloc(), ArpLock(), FreeTaskResList().
dos.doc/Open
AUTHOR: SDB (V9.0)
Revised:
^Larp.doc/ArpDupLock (V31)
NAME
ArpDupLock -- Duplicate a lock and track it.
SYNOPSIS
Lock = ArpDupLock( lock )
d0 d1
FUNCTION
This function is completely equivalent to the AmigaDOS DupLock(),
except that ArpLib will remember that you have duped this lock,
and will UnLock() for you when you CloseLibrary(ArpBase).
INPUTS
lock -- pointer to a lock
RESULTS
A lock or NULL, if no lock.
BUGS
None known.
SEE ALSO
DOS DOCUMENTATION, FreeTaskResList, ArpAlloc(), ArpAllocEntry(),
ArpClose().
^Larp.doc/ArpLock (V31)
NAME
ArpLock -- Get a lock and track it.
SYNOPSIS
Lock = ArpLock("name", accessmode)
d0 d1 d2
FUNCTION
This function is completely equivalent to the AmigaDOS Lock(),
except that ArpLib will remember that you have opened this lock,
and will UnLock() for you when you CloseLibrary(ArpBase).
INPUTS
name -- pointer to a null terminated string
accessmode -- a valid AmigaDOS access value.
RESULTS
A lock or NULL, if no lock.
BUGS
None known.
SEE ALSO
DOS DOCUMENTATION, FreeTaskResList, ArpAlloc(), ArpAllocEntry(),
ArpClose().
^Larp.doc/GetTracker (V31)
NAME
GetTracker -- Get a tracking node for resource tracking.
SYNOPSIS
Tracker = GetTracker() /* PRESERVES D0/D1/A0 */
A1
FUNCTION
This call creates a tracking node which you may use to track
whatever type of resource you want tracked. If you leave
the TRU_ID field null, this tracker is just considered as a
memory node, and properly freed. In fact, you can use
ArpAlloc to and build your own tracking node; all nodes have
the same basic structure, with the default being a simple
memory allocation.
This call preserves registers D0/D1/A0, unless the request
fails in which case D0 is set to 0 for your convenience,
as a NULL result. On sucess, register A1 is a pointer to
the tracking node, and the Z flag is set NOT-ZERO.
Normally for C language use, the details of tracking will be
hidden in a binding routine designed for the particular thing
you want to track.
Normally you should call this function prior to allocating
the resource you want to track, see the library functions like
ArpLock for an example of how to use this function efficiently.
The worst case as to what will happen if you use GetTracker
and then fall off the end of the world, is that the tracking node
will be treated as a ArpAlloc memory item, which will be freed
by FreeTaskResList or by a cleanup routine at some later time.
SEE ALSO
ArpAlloc, FreeTaskResList, ArpOpen, ArpUnLock, ArpDupLock.
Author: cdh
^Larp.doc/ArpAlloc (V31)
NAME
ArpAlloc -- Allocate memory and track.
SYNOPSIS
Memory = ArpAlloc( size_in_bytes )
d0 d0
FUNCTION
This function provides a simple memory allocation/tracking
mechanism. You can allocate memory with this function and,
when you CloseLibrary(ArpBase) or ArpExit(code), the memory
will be automatically freed for you. You can make multiple
calls to ArpAlloc(), each allocation will be tracked.
INPUTS
size_in_bytes - Amount of memory required.
RESULT
Pointer to a memory block with attributes (MEMF_PUBLIC | MEMF_CLEAR),
or zero, if an error occurred.
WARNINGS/ADDITIONAL CONSIDERATIONS
REMEMBER: You must call CloseLibrary(ArpBase) for the resource
freeing to occur.
SEE ALSO
ArpAllocEntry, FreeTaskResList, ArpOpen, ArpUnLock, ArpDupLock.
Author: SDB
Revised: Use ArpAllocEntry (version 8)
^Larp.doc/FreeTaskResList (V31)
NAME
FreeTaskResList -- Free tracked resources for this task
SYNOPSIS
BOOL = FreeTaskResList()
d0
FUNCTION
This function frees ALL resources tracked by arplibs resource
tracking mechanism. This includes memory as well as open
files and locks. Ordinarily, you will call this function
indirectly by CloseLibrary(ArpBase) or ArpExit(). This
mechanism allows easier exits (whether normal or abnormal)
than is usually found.
INPUTS
NONE
RESULT
TRUE if resource deallocation occurred, otherwise FALSE.
ADDITIONAL
The tracking scheme has been radically changed from eariler
versions of arplib, but this should not break any programs.
BUGS
None known.
Author: SDB
Revised: Track more stuff (SDB V9).
^Larp.doc/FreeTrackedItem (V31)
NAME
FreeTrackedItem -- Free a tracked item from a ResList
SYNOPSIS
FreeTrackedItem( ItemPtr )
A1
FUNCTION
Frees an individual tracked resource. You need the address of
the tracking node (which is returned by ArpAlloc or GetTracker,
or for functions ArpLock/ArpOpen/ArpDupLock, in register A1 as
the secondary result after the primary value in D0 )
The resource is removed from the tasks tracking list, automajikly.
BUGS
None known.
Author: CDH V18
^Larp.doc/GetAccess (V31)
NAME
GetAccess -- Locks access to a tracked resource.
SYNOPSIS
Pointer = GetAccess( tracker )
d0 A1
FUNCTION
This function is used in conjunction with FreeAccess() for
tracked items. If you call FreeAccess, a tracked item may
be freed by the OS during memory crunch. GetAccess is used
to try to reclaim the object for continued use.
When you call GetAccess, if the item has not been flushed, the
return value in D0 is the tracked item pointer (not the tracker),
and the item is locked so the system will not attempt to flush
it on you again.
If the system has FREED the tracked item, the return value from
the GetAccess call will be ZERO. In this case, it is best for
you to then call FreeTrackedItem on the tracker node, to free
the tracking link. Otherwise the link may cause fragmentation
until your task terminates or until you FreeTaskReslist.
BUGS
None Known.
AUTHOR: CDH V18
^Larp.doc/FreeAccess (V31)
NAME
FreeAccess -- Decrements use count for a tracked item.
SYNOPSIS
FreeAccess( Tracker )
A1
FUNCTION
Decrements the user count on a tracked item. If the user count
goes to (-1), the item may be freed during a memory crunch. To
find out if the item was freed, use GetAccess, which will return
NULL if the item is gone, or the value if it was not freed.
This maintains private values in the tracking node. If you
directly access this information, your program will probably
not work in future releases of ArpLibrary.
BUGS:
None Known.
AUTHOR
CDH V18
SHAR_EOF
# End of shell archive
exit 0