home *** CD-ROM | disk | FTP | other *** search
/ Otherware / Otherware_1_SB_Development.iso / amiga / programm / language / bcpl4ami.lzh / tripos / ramlib.doc < prev   
Encoding:
Text File  |  1988-12-07  |  9.8 KB  |  243 lines
  1.                         The BCPL Global Vector
  2.  
  3. Author: Bill Kinnersley
  4. Date: Mar 12, 1988
  5. Mail: Physics Dept.
  6.       Montana State University
  7.       Bozeman, MT 59717
  8. BITNET: iphwk@mtsunix1
  9. INTERNET: iphwk%mtsunix1.bitnet@cunyvm.cuny.edu
  10. UUCP: ...psuvax1!mtsunix1.bitnet!iphwk
  11.  
  12.  
  13. The Global Vector is a collection of everything a BPCL program
  14. might want to know.  Although a few slots contain data, most of
  15. them are entry addresses for the BCPL library routines.  There are
  16. three kinds of functions:
  17.  
  18.         a) BCPL functions.
  19. Here I've used the standard lower case BCPL name.
  20.  
  21.         b) Documented Amiga functions.
  22.        (AmigaDOS calls from C wind up here)
  23. I've used the name as it appears in the AmigaDOS manual.  Easily
  24. recognized by the fact that they're capitalized.
  25.  
  26.         c) Undocumented Amiga functions.
  27. These can be called only from BCPL.  I've tried to invent a meaningful
  28. name.
  29.  
  30.  
  31. Notation:
  32.  
  33. Just as &, * are used to denote "address of" and "contents of" for
  34. APTRs, I use @, ^ to denote "address of" and "contents of" for BPTRs.
  35. BOOL denotes a BCPL boolean (TRUE = -1, FALSE = 0)
  36. SIGN denotes a value +1, -1, or 0.
  37.  
  38.  
  39.     Contents of the Global Vector are listed below according to the
  40. byte offset in hexadecimal.  Arguments for each function are given in
  41. the order d1/d2/d3/d4.
  42.  
  43.         -84 - sysRequest(@line1, @line2, @line3)
  44.               Creates a System Requester with three given lines of text
  45.         -80 - char *toCStr(@string)
  46.               Converts a BCPL string to a C string.
  47.               (destructively, in place)
  48.         -7c - toBSTR(&src, @dest)
  49.               Converts a C string to a BCPL string.
  50.               (the user must supply the dest buffer)
  51.         -6c - BOOL Execute(&command, @input, @output)
  52.         -68 - BOOL IsInteractive(@FileHandle)
  53.         -64 - timeval *DateStamp(&time)
  54.         -60 - BOOL SetProtection(&name, mask)
  55.         -5c - BOOL SetComment(&name, &comment)
  56.         -54 - QueuePacket()
  57.         -50 - clearmem(@buf, lwlength)
  58.         -4c - SegList ^LoadSeg(&name)
  59.         -48 - MessagePort *CreateProc(&name, pri, seg, stackbytes)
  60.         -44 - long IoErr()
  61.         -40 - FileLock ^CurrentDir(@FileLock)
  62.         -3c - FileLock ^CreateDir(&name)
  63.         -38 - BOOL Info(@FileLock, &InfoData)
  64.         -34 - BOOL ExNext(@FileLock, &FileInfo)
  65.         -30 - BOOL Examine(@FileLock, &FileInfo)
  66.         -2c - FileLock ^Lock(&name, mode)
  67.         -28 - BOOL Rename(&oldname, &newname)
  68.         -24 - BOOL DeleteFile(&name)
  69.         -20 - long Seek(@FileHandle, pos, mode)
  70.         -18 - long Write(@FileHandle, &buf, len)
  71.          -c - long Read(@FileHandle, &buf, len)
  72.          -8 - strncpy(@src, @dest, n)
  73.          -4 - FileHandle ^Open(&name, mode)
  74.           0 - contains the lwsize of the GV
  75.           4 - start()
  76.               Contains the entry point of the current program
  77.           8 - Exit(code)
  78.           c - long multiply (arg1 & arg2)
  79.          10 - long divide (arg1 / arg2)
  80.          14 - long mod (arg1 % arg2)
  81.          18 - setIO(@IOStdReq, command, &data, length, offset)
  82.         The next two functions are used for packing and unpacking strings:
  83.          20 - packlw
  84.          24 - unpacklw
  85.          28 - long Res2(flag, res)
  86.               flag = TRUE means "Set the result"
  87.               flag = FALSE means "Get the result"
  88.          30 - contains BPTR to coroutine chain
  89.          34 - makeGVarea(@buf)
  90.          38 - Process *findtask()
  91.         The next two functions are used for addressing individual
  92.         bytes in memory:
  93.          3c - byte getbyte(@long, bytenumber)
  94.          40 - byte putbyte(@long, bytenumber)
  95.          44 - long level()
  96.               This returns a pointer to the current stack frame, to be
  97.               used as a marker when calling function 48
  98.          48 - longjump(level, label)
  99.          4c - allocMem(lwlength, reqs)
  100.          50 - longjump?(d1)
  101.          54 - doIO(@IORq)
  102.          58 - void sendIO(@IORq, @?)
  103.         The next group of functions implement the coroutine
  104.         mechanism (see article by Moody and Richards):
  105.          5c - createco(@coroutine, lwlength)
  106.              struct coroutine {
  107.                 BPTR colist;
  108.                 BPTR parent;
  109.                 APTR frame;
  110.                 APTR procedure;
  111.              }
  112.          60 - deleteco(@coroutine)
  113.          64 - callco(@coroutine, arg)
  114.          68 - cowait(result)
  115.          6c - resumeco(@coroutine)
  116.          70 - BOOL installSeg(@memseg)
  117.               The segment is assumed to be a BCPL module,
  118.               and its globals are installed in the GV
  119.         The next two functions create and destroy MemSegs:
  120.          74 - long ^getvec(lwlength)
  121.          78 - freevec(@long)
  122.          7c - BOOL openDevice(@IORq, @name, unit, flags)
  123.          80 - void closeDevice(@IORq)
  124.          84 - MessagePort &createproc(@segarray, stack, pri, @name)
  125.               This BCPL createproc differs from function 48:
  126.               user specifies the entire segarray, not just a seglist
  127.               stack size is in longwords, not bytes
  128.          88 - remProcess()
  129.          8c - FileLock ^ParentDir(@FileLock)
  130.          90 - void setSignals(&MsgPort, mask)
  131.          94 - BOOL clearSignals(mask)
  132.          98 - DOSAlert(alertnumber)
  133.          9c - RootNode @findRootNode()
  134.          a0 - bytelength readinput(&buf, bytelength)
  135.          a4 - DosPacket @taskwait()
  136.               Identical to function 190
  137.          a8 - putPkt(@DosPacket)
  138.          ac - writeoutput(&buf, bytelength)
  139.          b0 - packstring(@Array, @String)
  140.          b4 - unpackstring(@String, @Array)
  141.          b8 - holdTask(@memseg)
  142.          bc - Delay(?)
  143.          c0 - sendPacket(-, Process, Type, -, -, Arg1,...)
  144.          c4 - returnPacket(@DosPacket, res1, res2)
  145.          c8 - openWindow(leftedge, topedge, width, height, @title)
  146.          cc - FileLock @setCurDir(BOOL, @FileLock)
  147.          d0 - systemRequest(@line1, @line2, @line3)
  148.          d4 - writet(n)
  149.               Outputs n spaces
  150.          d8 - char rdch()
  151.          dc - unrdch()
  152.          e0 - wrch(char)
  153.          e4 - lwlength readinput(@buf, lwlength)
  154.          e8 - writeoutput(@buf, lwlength)
  155.         The next two functions open files for input/output:
  156.          ec - FileHandle ^findinput(&name)
  157.          f0 - FileHandle ^findoutput(&name)
  158.         The next two functions set the current input/output:
  159.          f4 - void selectinput(@FileHandle)
  160.          f8 - void selectoutput(@FileHandle)
  161.         The next two functions close the current input/output:
  162.         100 - endwrite()
  163.         The next two functions return the current input/output:
  164.         104 - FileHandle @Input()
  165.         108 - FileHandle @Output()
  166.         10c - readn()
  167.               Reads an integer from the current input
  168.         110 - newline()
  169.         114 - writei(number, width)
  170.         118 - writen(number)
  171.         11c - writehex(number, width)
  172.         120 - writeoct(number, width)
  173.         124 - writes(@string)
  174.         128 - writef(@format, arg1, arg2, ...)
  175.               The format string may contain:
  176.                 %C - ASCII character
  177.                 %In - decimal number, width n   %N - decimal number
  178.                 %On - octal number, width n     %S - string
  179.                 %Tn - n spaces                  %Un - unsigned long
  180.                 %Xn - hex number, width n       %$ - suppress arg
  181.         12c - toupper(char)
  182.         130 - long charcmp(char1, char2)
  183.               Returns the numerical difference (ignoring case)
  184.         134 - long strcmp(@String1, @String2)
  185.               Returns the difference of first chars that don't match
  186.         138 - rdargs(@template)
  187.               This function parses the command line according to a
  188.               given template (format)
  189.               (See AmigaDOS User's Manual, Sect 1.4.5)
  190.               Result: A1 is APTR to array of BSTRs, or 0 in case of error.
  191.         13c - rdline()
  192.         140 - subString(@string, @substring)
  193.         144 - SegList ^load(@filename)
  194.         148 - UnLoadSeg(@seg)
  195.         150 - tidyup()
  196.               This slot is reserved for an optional user-defined function
  197.               which may be used to provide a clean program termination
  198.         154 - addDevice(@name)
  199.         158 - datestamp(@time)
  200.         15c - BOOL WaitForChar(@FileHandle, time)
  201.         160 - long execLib(LVOffset, d0, d1, a0, a1, a2)
  202.         164 - Array @findSegArray()
  203.         168 - deleteObject(@name)
  204.         16c - rename(@oldname, @newname)
  205.         170 - contains APTR to IntuitionBase
  206.         174 - Close(@FileHandle)
  207.         The next two functions access memory a word at a time:
  208.         178 - getword(longaddress, wordnumber)
  209.         17c - putword(longaddress, wordnumber)
  210.         190 - DosPacket ^taskwait()
  211.               Identical to function a4
  212.         194 - execute(? , @in, @out)
  213.         198 - FileLock ^deviceproc(@filename)
  214.         19c - libcall(libbase, LVOffset, d0, d1, a0, a1)
  215.         1a4 - MsgPort ^findConsoleHandler()
  216.         1a8 - MsgPort ^findFileHandler()
  217.         1ac - extractDeviceName(@buf, bufsize, @name , flag)
  218.         1b0 - FileLock ^lock(@name)
  219.               (shared access) - Same as function 1ec
  220.         1b4 - UnLock(@FileLock)
  221.         The next two functions access memory as a record structure:
  222.         1b8 - getlong(longoffset, @struct)
  223.         1bc - putlong(longoffset, @struct, data)
  224.         1c0 - FileHandle ^openfile(@devinfo, @filename)
  225.         1c4 - FileLock ^DupLock(@FileLock)
  226.         1c8 - makesysreq(count, pkt, proc)
  227.         1cc - strcpy(@src, @dest)
  228.         1e4 - runLoadedCode(@codeseg, stackbytes, @cmdline, cmdlinelength)
  229.         1ec - FileLock ^lock(@name)
  230.               Same as function 1b0
  231.         1f0 - DevInfo ^findDevInfo(@name)
  232.         1f4 - createDir(@name)
  233.         1f8 - SIGN compareTime(@timeval, @timeval)
  234.         1fc - timerIO(command, @IOStdReq, secs, usecs)
  235.         200 - settime(@timeval)
  236.         214 - contains CLI command
  237.         218 - CommandLineInterpreter ^findCLI()
  238.  
  239. There are also two utility math routines which can be addressed by their
  240. offset from a5:
  241.         10(a5) : D1 = D1 * D2
  242.         12(a5) : D1 = D1 / D2, D2 = D1 % D2
  243.