afb@j.cc.purdue.edu (Matthew Bradburn) (12/11/87)
Here is the documentation to the calls available with the arp.library. (See earlier article in comp.binaries.amiga for the library itself.) Matthew Bradburn ARPA: afb@j.cc.purdue.edu UUCP: j.cc.purdue.edu!afb BITNET: bradburn@purccvm # 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: # README # arpbase.i # This archive created: Thu Dec 10 15:33:42 1987 # By: Matthew Bradburn (Purdue University) echo shar: extracting README '(878 characters)' cat << \SHAR_EOF > README The documentation here can get you started using arp.library to assist you with program development; we will have a more complete programmers package available shortly. We have people working on binding routines for both Manx and Lattice C compilers, as well as TDI Modula II. The file "include/arpbase.i" has the _LVO offsets needed for accessing the files in arp.library, as well as defining the public data structures and equates needed to use Arp functions. For further info about programming with arp.library, and for including Arp with commercial program releases, please send an SASE to the address below. We would appreciate your contacting us directly to insure you have the latest versions of any programs and arp.library. Thanks- ...cheath Mail to: ARP Programming c/o Microsmiths Inc PO Box 561 Cambridge, MA 02140 BIX: cheath CIS:74216,2117 SHAR_EOF if test 878 -ne "`wc -c README`" then echo shar: error transmitting README '(should have been 878 characters)' fi echo shar: extracting arpbase.i '(15863 characters)' cat << \SHAR_EOF > arpbase.i IFND LIBRARIES_ARPBASE_I LIBRARIES_ARPBASE_I SET 1 *********************************************************************** * * AmigaDOS Replacement Project -- Library Include File (Assembler) * *********************************************************************** * * History: * * Version: arpbase.i,v 0.40 02/05/87 * * Created by: SDB * Revised: SDB (v 5.00 05/31/87) * *---- Added meaningful alert numbers, revised macros, * *---- updated ArpBase structure to reflect current state. * *---- Added cheath's ASSIGN return codes as equates. * *---- plus usual grunt work (revisions, lvo's, etc.) * SDB (v6.04) * cdh V7.0 * *---- added IntuiBase and GfxBase to ArpBase * sdb V7.2 * *---- rearranged for more efficient lib code (ouch). * *---- DosBase IntuiBase and GfxBase have *all* changed! * *---- Few more alert #'s now get returned, * *---- new GURU macro replaces provincial MYALERT. * sdb v12 newstuff, see docs * cdh V14 Added dos.library offsets, everybody moves! * cdh V15 Added (volatile!) FindFirst etc offsets * cdh V19 Added structs and constants for wildcards * cdh V31 Final edit for V1.0 ARP 10/7/87 * *********************************************************************** * * Copyright (c) 1987, by Scott Ballantyne * * The arp.library, and related code and files may be freely used * by supporters of ARP. Modules in the arp.library may not be * extracted for use in independent code, but you are welcome to * provide the arp.library with your work and call on it freely. * * You are equally welcome to add new functions, improve the ones * within, or suggest additions/removals. * * BCPL programs are not welcome to call on the arp.library. * The welcome mat is out to all others. *********************************************************************** IFND EXEC_TYPES_I INCLUDE "exec/types.i" ENDC !EXEC_TYPES_I IFND EXEC_LIBRARIES_I INCLUDE "exec/libraries.i" ENDC !EXEC_LIBRARIES_I IFND EXEC_LISTS_I INCLUDE "exec/lists.i" ENDC !EXEC_LISTS_I IFND EXEC_SEMAPHORES_I INCLUDE "exec/semaphores.i" ENDC !EXEC_SEMAPHORES_I IFND LIBRARIES_DOS_I INCLUDE "libraries/dos.i" ENDC !LIBRARIES_DOS_I STRUCTURE ArpBase,LIB_SIZE ; Standard library node ULONG SegList ; pointer to seglist of loaded library UBYTE Flags ; See definitions below. UBYTE pad LONG AB_reserved ; ArpLib's use only!! CPTR EnvBase ; ptr to environment ULONG DosBase ; Cached DosBase ULONG GfxBase ; Cached GfxBase ULONG IntuiBase ; Cached IntuitionBase STRUCT ResLists,MLH_SIZE ; Tracked Resources LABEL ArpLib_Sizeof *--------------- Following is here only for compatibility with MANX, *--------------- don't use in new code! STRUCTURE EnvLib,LIB_SIZE ; fake library for MANX CPTR EnvSpace ; access only when Forbidden! ULONG EnvSize ; size of environment LABEL EnvLib_Sizeof *---------- Flags bit definitions * * NOTE: You can check these, but better not change them! * It is currently undetermined how these will be set, but they should * only be set by the user, or by the startup code. Possibly we could * check for an environment variable. This is likely to be the best idea. * * NOTE FOR THOSE WRITING LIBRARY CODE: * Routines which use these flags to decide which escape or wildcards to * use default to the BCPL version if neither one is set. For consistancy, * please observe the same convention in your code. * *------------------------------------------------------- BITDEF ARP,WILD_WORLD,0 ; use Wildcards/escapes like rest of world BITDEF ARP,WILD_BCPL,1 ; use Wildcards/escapes like current dos. *----------- Rest of library style stuff ArpName MACRO dc.b 'arp.library',0 ds.w 0 ENDM *---------- Current arp.library version. ArpVersion EQU 31 *---------- Arp alert numbers, the cutesy BAD CODE one is gone. *---------- We will have to get these blessed by Amiga soon, or changed, or whatever. *-------- Alert Object AO_ArpLib EQU $00008036 *-------- Specific Alerts you can get when opening ArpLib. -----------* *------- ONLY ARPLIB can return these, you should construct your own, preferably *------- NON dead end alerts, for example, if you can't open ARP: *------- MYALERT AG_OpenLib!AO_ArpLib *---------------------------------------------------------------------* AN_ArpLib EQU $03600000 AN_ArpNoMem EQU $03610000 ; Arplibrary out of memory. AN_ArpTaskArray EQU $83610001 ; No memory for task array AN_ArpInputMem EQU $03610002 ; No memory for input buffer. AN_ArpNoMakeEnv EQU $83610003 ; No memory for EnvLib AN_ArpNoDOS EQU $83630001 ; Can't open DOS library AN_ArpNoGfx EQU $83630002 ; Can't open graphics AN_ArpNoIntuit EQU $83630003 ; Can't open intuition AN_ArpObsFunc EQU $03600001 ; Call of obsolete function. AN_ArpScattered EQU $83600002 ; Scatter loading not allowed for lib. *-------- *---------- Tiny ALERT macro, assumes ExecBase is already in A6, also that you *---------- have nothing important in d7, also that you want to return immediately. GURU MACRO * optional alert number IFNC '\1','' move.l #\1,D7 ENDC jmp _LVOAlert(a6) ENDM MYALERT MACRO * ancient compatibility GURU \1 ENDM *------------- Library Vector Offsets. * * This macro is used to define the DOS offsets without redefining the symbols- * To get the DOS symbols, INCLUDE dos_lib.i * LIBSKP MACRO COUNT_LIB SET COUNT_LIB-LIB_VECTSIZE ENDM LIBINIT LIBSKP _LVOOpen LIBSKP _LVOClose LIBSKP _LVORead LIBSKP _LVOWrite LIBSKP _LVOInput LIBSKP _LVOOutput LIBSKP _LVOSeek LIBSKP _LVODeleteFile LIBSKP _LVORename LIBSKP _LVOLock LIBSKP _LVOUnLock LIBSKP _LVODupLock LIBSKP _LVOExamine LIBSKP _LVOExNext LIBSKP _LVOInfo LIBSKP _LVOCreateDir LIBSKP _LVOCurrentDir LIBSKP _LVOIoErr LIBSKP _LVOCreateProc LIBSKP _LVOExit LIBSKP _LVOLoadSeg LIBSKP _LVOUnLoadSeg LIBSKP _LVOGetPacket LIBSKP _LVOQueuePacket LIBSKP _LVODeviceProc LIBSKP _LVOSetComment LIBSKP _LVOSetProtection LIBSKP _LVODateStamp LIBSKP _LVODelay LIBSKP _LVOWaitForChar LIBSKP _LVOParentDir LIBSKP _LVOIsInteractive LIBSKP _LVOExecute *** LIBDEF _LVOPrintf ; Print formatted data on current output. LIBDEF _LVOFPrintf ; Print formatted data on file. LIBDEF _LVOPuts ; Print string\n on stdout. LIBDEF _LVOReadLine ; Get a line from stdin. LIBDEF _LVOGADS ; Get args using template LIBDEF _LVOAtol ; Convert Ascii to long int. LIBDEF _LVOEscapeString ; Handle escapes in string. LIBDEF _LVOCheckAbort ; Check for CNTRL-C LIBDEF _LVOCheckBreak ; Check for CNTRL c d e or f LIBDEF _LVOGetenv ; Get value of environment variable LIBDEF _LVOSetenv ; Set value of environment variable LIBDEF _LVOFileRequest ; Filename Requester LIBDEF _LVOCloseWindowSafely ; Closes shared IDCMP window w/o GURU LIBDEF _LVOCreatePort ; Create a message port LIBDEF _LVODeletePort ; Delete a message port LIBDEF _LVOSendPacket ; Send a dos packet LIBDEF _LVOInitStdPacket ; initialize a standard packet LIBDEF _LVOPathName ; Return Complete pathname of file/directory. LIBDEF _LVOAssign ; Assign a logical device name LIBDEF _LVODosAllocMem ; DOS compatible memory allocator LIBDEF _LVODosFreeMem ; DOS compatible memory free-er LIBDEF _LVOBtoCStr ; Copy a BCPL string to C string LIBDEF _LVOCtoBStr ; Copy a C string to BCPL string LIBDEF _LVOGetDevInfo ; Get pointer to head of DevInfo LIBDEF _LVOFreeTaskResList ; Free Tracked resources for this task LIBDEF _LVOArpExit ; Exit, freeing tracked resources. LIBDEF _LVOArpAlloc ; Allocate memory with tracking LIBDEF _LVOArpAllocMem ; Track AllocMem allocation LIBDEF _LVOArpOpen ; Track open files LIBDEF _LVOArpDupLock ; Track duped locks LIBDEF _LVOArpLock ; Track allocated locks LIBDEF _LVORListAlloc ; Like ArpAlloc for free reslist LIBDEF _LVOFindCLI ; Get a process given a task number LIBDEF _LVOQSort ; Quick Sort LIBDEF _LVOPatternMatch ; Match a string with a pattern (wildcards!) LIBDEF _LVOFindFirst ; Search directory w/wildcards LIBDEF _LVOFindNext ; Continue search w/wildcards LIBDEF _LVOFreeAnchorChain ; Free mem from FindFirst/Next LIBDEF _LVOCompareLock ; Compare two disk locks LIBDEF _LVOFindTaskResList ; Find resource list for this task LIBDEF _LVOCreateTaskResList ; Create a new nested task reslist LIBDEF _LVOFreeResList ; Free an un-attached reslist LIBDEF _LVOFreeTrackedItem ; Free a tracked item LIBDEF _LVOGetTracker ; Get a tracker node LIBDEF _LVOGetAccess ; Lock access to a node LIBDEF _LVOFreeAccess ; Allow resource to flush if lowmem LIBDEF _LVOFreeDAList ; Free a DosAllocmem list LIBDEF _LVOAddDANode ; Add a node to a DA list LIBDEF _LVOAddDADevs ; Add devices to a DA list LIBDEF _LVOStrcmp ; Compare two null-terminated strs LIBDEF _LVOStrncmp ; Compare up to N chars LIBDEF _LVOToupper ; Convert to UC LIBDEF _LVOSyncRun ; Run program as subroutine *** *---------- Return codes you can get from calling Assign: ASSIGN_OK EQU 0 ASSIGN_NODEV EQU 1 ASSIGN_FATAL EQU 2 ASSIGN_CANCEL EQU 3 ; Can't cancel a VOLUME *--------- Size of buffer you need for ReadLine MaxInputBuf EQU 256 *--------- Input structure for File Requester FRB_DoWildFunc equ 7 FRB_DoMsgFunc equ 6 FCHARS equ 32 ; Directory name sizes DSIZE equ 33 * SET ALL OTHER FLAGS TO NULL - * They will be used in later revs of Arp.library. * If you set them non-null, they will do something besides default. * You may not be set up for it. STRUCTURE FR_struct,0 APTR FR_Hail ; Hailing text APTR FR_Ddef ; *Filename array (FCHARS+1) APTR FR_Ddir ; *Directory array (DSIZE+1) APTR FR_Wind ; Window requesting or NULL SHORT FR_Flags ; Control. See above. SET TO NULL. APTR FR_WildFunc ; Func to call for wildcards APTR FR_MsgFunc ; Func to call with IntuiMessages *---------- Structures and constants used by the wildcard routines P_ANY EQU $80 P_SINGLE EQU $81 P_ORSTART EQU $82 P_ORNEXT EQU $83 P_OREND EQU $84 P_TAG EQU $85 P_TAGEND EQU $86 P_NOTCLASS EQU $87 P_CLASS EQU $88 P_REPBEG EQU $89 P_REPEND EQU $8A COMPLEX_BIT EQU 1 EXAMINE_BIT EQU 2 ERROR_BUFFER_OVERFLOW EQU 303 ERROR_INTERNAL EQU 999 ERROR_BREAK EQU 304 BUFSIZ EQU 200 DOS_TRUE EQU 0 DOS_FALSE EQU -1 MAXFNAME EQU 200 * This is the structure you pass to FindFirst/FindNext. * In it you can set AP_BREAKBITS to be the bits you want to match * for break checking while the directory is being searched. * Also you may allocate a buffer at AP_BUF, the size of which is * in AP_LENGTH, where the full path name of the current entry will * be built. If AP_LENGTH is 0, the path name will not be built. STRUCTURE AP,0 APTR AP_BASE APTR AP_LAST LONG AP_BREAKBITS LONG AP_FOUNDBREAK APTR AP_LENGTH STRUCT AP_INFO,fib_SIZEOF LABEL AP_BUF LABEL AP_SIZEOF STRUCTURE AN,0 APTR AN_NEXT APTR AN_PRED LONG AN_LOCK APTR AN_INFO LONG AN_STATUS ; Text must be longword aligned for passing to dos WORD AN_TEXT ;Account for LABEL AN_SIZEOF * Structure used by AddDANode, AddDADevs, FreeDAList * This structure is used to create lists of names, * which normally are devices, assigns, volumes, files, or directories STRUCTURE DirectoryEntry,0 LONG DA_Next BYTE DA_Type BYTE DA_Flags LABEL DA_Stuff LABEL DE_SIZEOF DLB_DEVICES equ 0 DLB_DISKONLY equ 1 ; If only DISK devices DLB_VOLUMES equ 2 DLB_DIRS equ 3 DLX_FILE equ 0 DLX_DIR equ 8 DLX_DEVICE equ 16 DLX_VOLUME equ 24 DLX_UNMOUNTED equ 32 DLX_ASSIGN equ 40 ************************************************************************ * * ResLists * This list is used to track resources, normally within a Task. * Each ResList has a single-linked node linking together ResLists; this * list is maintained in ArpBase now but ideally would use TC_UserData, * so the ResList for a task could be found more quickly. However, there * must also be a link so ResLists can be maintained in ArpBase, for * Resource Tracking. To facilitate this at a later data, we have * added the ReservedList field, which could be used if ArpBase gets * burned into ROM. * * NOTE: This is a DosAllocMem'd list, with length @-4 STRUCTURE ArpResList,0 STRUCT ARL_node,MLN_SIZE ; Links these together LONG TaskID STRUCT FirstItem,MLH_SIZE APTR ARL_link ; For temp removal from task rlist LABEL RL_SIZEOF * Tracked Items * Each item in the list has a double-link node which is used to * attach to the FirstItem list header in a ResList. All list items are * based on a simple memory allocation; the generic node is a DosAllocMem'd * memory block set to all NULL for the control fields. This makes it very * easy to track the nodes themselves, in case there is a problem during * allocation. STRUCTURE TrackedResource,0 STRUCT TR_Node,MLN_SIZE ; Double linked pointer BYTE TR_Flags ; See flag bits below BYTE TR_Lock ; Used by GetAccess/FreeAccess SHORT TR_ID ; ID for this item class APTR TR_Stuff ; Whatever the dude wants to free. LONG TR_Extra ; Unused now, even to memchunk size LABEL TR_SIZEOF * The function "GetTracker" will allocate a generic tracking node, * which is a minimum-sized memory block passed back to the user. * The pointer the user gets actually points at the TR_Stuff node, * rather than at the head of the list. The user-accessible fields are * below: STRUCTURE UserResource,-2 SHORT TRU_ID APTR TRU_Stuff LONG TRU_Extra * See discussion of the TRU_Extra field below; it is always allocated * because the minimum memory grain size is 8 bytes, and this extra * field actually does not require any extra memory. * Tracked Item Types * The id types below show the types of resources which may * be tracked in a resource list. TRAK_AAMEM equ 0 ; Default generic (ArpAlloc) element TRAK_LOCK equ 1 ; File Lock TRAK_FILE equ 2 ; Opened File TRAK_WINDOW equ 3 ; Window (see discussion) TRAK_SCREEN equ 4 ; Screen TRAK_LIBRARY equ 5 ; Opened library TRAK_DAMEM equ 6 ; Pointer to DosAllocMem block TRAK_MEMLIST equ 7 ; Exec Memlist TRAK_SEGLIST equ 8 ; Program Segment List TRAK_RESLIST equ 9 ; ARP (nested) ResList TRAK_MEM equ 10 ; Memory ptr/length TRAK_GENERIC equ 11 ; Generic Element TRAK_DALIST equ 12 ; DAlist ( as used by file request ) TRAK_ANCHOR equ 13 ; Anchor chain TRACK_MAX equ 13 ; Anything else is tossed. * For TRAK_GENERIC, you set up a task function to be called when * an item is freed. This is very dangerous if not used properly. * PROGRAMMER BEWARE. ( If you leave a relist untracked, too bad ) TG_FuncAddr equ TR_Extra TG_VALUE equ TR_Stuff * For TRAK_WINDOW, set the TW_OTHER field if this window shares a msgport * and the msgport should not be freed TW_WINDOW equ TR_Extra * NOTE - THINGS IN THIS LIST MUST NOT DEPEND ON THE TASK STILL EXISTING * Thus, no DeletePort or RemTask. This is to allow a Flush executable * to be created which will go throug all of the Tracked list, and for * tasks that exited improperly, free the resources. * Special Considerations * The TR_Lock and TR_Flags bytes have special meaning. These * are internally managed fields, which should not be touched by the * application. * The TR_Lock field is managed by GetAccess/FreeAccess. If * this field is -1, the resource being tracked may be freed at will * by the TRB_UNLINK equ 7 ; Bit for freeing the node TRB_RELOC equ 6 ; This element may be relocated!!! ; ( This bit is not used yet ) TRB_MOVED equ 5 ; Bit set if the item moved. TRV_UNLINK equ 1<<TRB_UNLINK TRV_RELOC equ 1<<TRB_RELOC ************************************************************************** *---------- handy macros LINKEXE MACRO LINKLIB _LVO\1,4 ENDM * LINKDOS now uses ArpBase * CALLDOS was nuked, to reduce confusion LINKDOS MACRO jsr _LVO\1(a6) ENDM CALLEXE MACRO move.l 4,a6 jsr _LVO\1(a6) ENDM * SYSCALL re-revised for only one arg * DosBase should always use ArpBase, or DosBase, in A6 SYSCALL MACRO CALLLIB _LVO\1 ENDM ENDC !LIBRARIES_ARPBASE_I SHAR_EOF if test 15863 -ne "`wc -c arpbase.i`" then echo shar: error transmitting arpbase.i '(should have been 15863 characters)' fi # End of shell archive exit 0