Club Amiga de Montreal

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

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 073.lha / Arp / documentation / Arp31.docs < prev next >

Wrap

Text File | 1986-11-20 | 59.9 KB | 1,980 lines

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 arp.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: arp.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: arp.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: arp.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 arp.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: arp.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: arp.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: arp.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 arp.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 arp.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 arp.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. arp.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 arp.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. arp.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 ). arp.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" arp.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: arp.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: arp.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: arp.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: arp.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) arp.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. arp.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 arp.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: arp.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: arp.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: arp.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 arp.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. arp.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 arp.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 arp.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 arp.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 arp.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: (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! 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 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 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 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! 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 arp.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. arp.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 arp.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 arp.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: arp.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(). arp.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(). arp.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 arp.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) arp.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). arp.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 arp.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 arp.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