The BCPL Global Vector Author: Bill Kinnersley Date: Mar 12, 1988 Mail: Physics Dept. Montana State University Bozeman, MT 59717 BITNET: iphwk@mtsunix1 INTERNET: iphwk%mtsunix1.bitnet@cunyvm.cuny.edu USENET: lll-crg!umt!mts-cs!uphwk The Global Vector is a collection of everything a BPCL program might want to know. Although a few slots contain data, most of them are entry addresses for the BCPL library routines. There are three kinds of functions: a) BCPL functions. Here I've used the standard lower case BCPL name. b) Documented Amiga functions. (AmigaDOS calls from C wind up here) I've used the name as it appears in the AmigaDOS manual. Easily recognized by the fact that they're capitalized. c) Undocumented Amiga functions. These can be called only from BCPL. I've tried to invent a meaningful name. Notation: Just as &, * are used to denote "address of" and "contents of" for APTRs, I use @, ^ to denote "address of" and "contents of" for BPTRs. BOOL denotes a BCPL boolean (TRUE = -1, FALSE = 0) SIGN denotes a value +1, -1, or 0. Contents of the Global Vector are listed below according to the byte offset in hexadecimal. Arguments for each function are given in the order d1/d2/d3/d4. -84 - sysRequest(@line1, @line2, @line3) Creates a System Requester with three given lines of text -80 - char *toCStr(@string) Converts a BCPL string to a C string. (destructively, in place) -7c - toBSTR(&src, @dest) Converts a C string to a BCPL string. (the user must supply the dest buffer) -6c - BOOL Execute(&command, @input, @output) -68 - BOOL IsInteractive(@FileHandle) -64 - timeval *DateStamp(&time) -60 - BOOL SetProtection(&name, mask) -5c - BOOL SetComment(&name, &comment)Üj -54 - QueuePacket() -50 - clearmem(@buf, lwlength) -4c - SegList ^LoadSeg(&name) -48 - MessagePort *CreateProc(&name, pri, seg, stackbytes) -44 - long IoErr() -40 - FileLock ^CurrentDir(@FileLock) -3c - FileLock ^CreateDir(&name) -38 - BOOL Info(@FileLock, &InfoData) -34 - BOOL ExNext(@FileLock, &FileInfo) -30 - BOOL Examine(@FileLock, &FileInfo) -2c - FileLock ^Lock(&name, mode) -28 - BOOL Rename(&oldname, &newname) -24 - BOOL DeleteFile(&name) -20 - long Seek(@FileHandle, pos, mode) -18 - long Write(@FileHandle, &buf, len) -c - long Read(@FileHandle, &buf, len) -8 - strncpy(@src, @dest, n) -4 - FileHandle ^Open(&name, mode) 0 - contains the lwsize of the GV 4 - start() Contains the entry point of the current program 8 - Exit(code) c - long multiply (arg1 & arg2) 10 - long divide (arg1 / arg2) 14 - long mod (arg1 % arg2) 18 - setIO(@IOStdReq, command, &data, length, offset) The next two functions are used for packing and unpacking strings: 20 - packlw 24 - unpacklw 28 - long Res2(flag, res) flag = TRUE means "Set the result" flag = FALSE means "Get the result" 30 - contains BPTR to coroutine chain 34 - makeGVarea(@buf) 38 - Process *findtask() The next two functions are used for addressing individual bytes in memory: 3c - byte getbyte(@long, bytenumber) 40 - byte putbyte(@long, bytenumber) 44 - long level() This returns a pointer to the current stack frame, to be used as a marker when calling function 48 48 - longjump(level, label) 4c - allocMem(lwlength, reqs) 50 - longjump?(d1) 54 - doIO(@IORq) 58 - void sendIO(@IORq, @?) The next group of functions implement the coroutine mechanism (see article by Moody and Richards): 5c - createco(@coroutine, lwlength) struct coroutine { BPTR colist; BPTR parent; APTR frame; APTR procedure; } 60 - deleteco(@coroutine) 64 - callco(@coroutine, arg) 68 - cowait(result) 6c - resumeco(@coroutine) 70 - BOOL installSeg(@memseg) The segment is assumed to be a BCPL module, and its globals are installed in the GV The next two functions create and destroy MemSegs: 74 - long ^getvec(lwlength) 78 - freevec(@long) 7c - BOOL openDevice(@IORq, @name, unit, flags) 80 - void closeDevice(@IORq) 84 - MessagePort &createproc(@segarray, stack, pri, @name) This BCPL createproc differs from function 48: user specifies the entire segarray, not just a seglist stack size is in longwords, not bytes 88 - remProcess() 8c - FileLock ^ParentDir(@FileLock) 90 - void setSignals(&MsgPort, mask) 94 - BOOL clearSignals(mask) 98 - DOSAlert(alertnumber) 9c - RootNode @findRootNode() a0 - bytelength readinput(&buf, bytelength) a4 - DosPacket @taskwait() Identical to function 190 a8 - putPkt(@DosPacket) ac - writeoutput(&buf, bytelength) b0 - packstring(@Array, @String) b4 - unpackstring(@String, @Array) b8 - holdTask(@memseg) bc - Delay(?) c0 - sendPacket(-, Process, Type, -, -, Arg1,...) c4 - returnPacket(@DosPacket, res1, res2) c8 - openWindow(leftedge, topedge, width, height, @title) cc - FileLock @setCurDir(BOOL, @FileLock) d0 - systemRequest(@line1, @line2, @line3) d4 - writet(n) Outputs n spaces d8 - char rdch() dc - unrdch() e0 - wrch(char) e4 - lwlength readinput(@buf, lwlength) e8 - writeoutput(@buf, lwlength) The next two functions open files for input/output: ec - FileHandle ^findinput(&name) f0 - FileHandle ^findoutput(&name) The next two functions set the current input/output: f4 - void selectinput(@FileHandle) f8 - void selectoutput(@FileHandle) The next two functions close the current input/output: 100 - endwrite() The next two functions return the current input/output: 104 - FileHandle @Input() 108 - FileHandle @Output() 10c - readn() Reads an integer from the current input 110 - newline() 114 - writei(number, width) 118 - writen(number) 11c - writehex(number, width) 120 - writeoct(number, width) 124 - writes(@string) 128 - writef(@format, arg1, arg2, ...) The format string may contain: %C - ASCII character %In - decimal number, width n %N - decimal number %On - octal number, width n %S - string %Tn - n spaces %Un - unsigned long %Xn - hex number, width n %$ - suppress arg 12c - toupper(char) 130 - long charcmp(char1, char2) Returns the numerical difference (ignoring case) 134 - long strcmp(@String1, @String2) Returns the difference of first chars that don't match 138 - rdargs(@template) This function parses the command line according to a given template (format) (See AmigaDOS User's Manual, Sect 1.4.5) Result: A1 is APTR to array of BSTRs, or 0 in case of error. 13c - rdline() 140 - subString(@string, @substring) 144 - SegList ^load(@filename) 148 - UnLoadSeg(@seg) 150 - tidyup() This slot is reserved for an optional user-defined function which may be used to provide a clean program termination 154 - addDevice(@name) 158 - datestamp(@time) 15c - BOOL WaitForChar(@FileHandle, time) 160 - long execLib(LVOffset, d0, d1, a0, a1, a2) 164 - Array @findSegArray() 168 - deleteObject(@name) 16c - rename(@oldname, @newname) 170 - contains APTR to IntuitionBase 174 - Close(@FileHandle) The next two functions access memory a word at a time: 178 - getword(longaddress, wordnumber) 17c - putword(longaddress, wordnumber) 190 - DosPacket ^taskwait() Identical to function a4 194 - execute(? , @in, @out) 198 - FileLock ^deviceproc(@filename) 19c - libcall(libbase, LVOffset, d0, d1, a0, a1) 1a4 - MsgPort ^findConsoleHandler() 1a8 - MsgPort ^findFileHandler() 1ac - extractDeviceName(@buf, bufsize, @name , flag) 1b0 - FileLock ^lock(@name) (shared access) - Same as function 1ec 1b4 - UnLock(@FileLock) The next two functions access memory as a record structure: 1b8 - getlong(longoffset, @struct) 1bc - putlong(longoffset, @struct, data) 1c0 - FileHandle ^openfile(@devinfo, @filename) 1c4 - FileLock ^DupLock(@FileLock) 1c8 - makesysreq(count, pkt, proc) 1cc - strcpy(@src, @dest) 1e4 - runLoadedCode(@codeseg, stackbytes, @cmdline, cmdlinelength) 1ec - FileLock ^lock(@name) Same as function 1b0 1f0 - DevInfo ^findDevInfo(@name) 1f4 - createDir(@name) 1f8 - SIGN compareTime(@timeval, @timeval) 1fc - timerIO(command, @IOStdReq, secs, usecs) 200 - settime(@timeval) 214 - contains CLI command 218 - CommandLineInterpreter ^findCLI() There are also two utility math routines which can be addressed by their offset from a5: 10(a5) : D1 = D1 * D2 12(a5) : D1 = D1 / D2, D2 = D1 % D2