home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / cpmhelp / c.hlp < prev    next >
Text File  |  1994-07-27  |  17KB  |  491 lines
  1. Invoking BDS C using C.SUB
  2. Overview of the BDS C Language System
  3. Overview -- C Compiler, Pass 1
  4. Overview -- C Compiler, Pass 2
  5. Overview -- C Linker
  6. Overview -- C Librarian
  7. Overview -- C Skeleton File
  8. Variable Types
  9. Braces
  10. Variable Accessing
  11. ARIES-1 C Library
  12. Special I/O using CIO
  13. :Invoking BDS C using C.SUB
  14.  
  15.      BDS  C  may  be invoking either by the conventional means  or  by 
  16. using  the  SUBMIT file C.SUB.   If the SUBMIT file  is  used,  it  is 
  17. engaged as follows --
  18.  
  19.           SUBMIT C filename
  20.  
  21. where  'filename'  is the name of 'filename.C',  the file to  compile.  
  22. Note that the user is NOT to to type filename.C,  but is just to  type 
  23. filename.
  24.  
  25.      As  execution  of the two passes of the compiler and  the  linker 
  26. proceeds,  the  user  will be given the chance to abort processing  at 
  27. various  critical  points  in  the process by  the  execution  of  the 
  28. ABORTSUB  program.   If  an  error has occurred  during  the  previous 
  29. processing, ABORT when this program is executed.
  30.  
  31.  
  32. :Overview of the BDS C Language System
  33.  
  34.     The main components of C are: 4 executable programs,
  35. a standard library file, and one skeleton run-time subroutine
  36. file.
  37.  
  38. A description of each follows:
  39. :Overview -- C Compiler, Pass 1
  40.  
  41. CC1:    Because C loads the entire source file into memory
  42.     in one shot, the compilation is broken up into two
  43.     phases (not "passes", strictly; The two phases end
  44.     up taking about 8 passes to actually implement),
  45.     maximizing the amount of memory available for the
  46.     source file.
  47.     CC1, the first half of the compiler, accepts a C
  48.     source file with any filename and extension (say,
  49.     "foo.c") and writes out a temporary file (with the
  50.     same filename and extension ".CCI") containg a symbol
  51.     table and an encoded form of the source code.
  52.  
  53.     The file extension ".C" is NOT assumed for the
  54.     input file, so saying "FOO" for "FOO.C" would not
  55.     work.
  56.  
  57.  
  58.     If the source file name is preceded by a disk
  59.     designation, then the input is taken from the specified
  60.     disk and the ouput is also written to that disk.
  61.  
  62.     If any errors are detected during CC1, the output
  63.     file will not be written.
  64.  
  65.     In addition to the name of the source file, a few
  66.     options may also be specified on the command line
  67.     by preceding the option list with a dash (-):
  68.  
  69.     s     causes undeclared identifiers to be implicitly
  70.             declared as integer variables, wherever possible.
  71.  
  72.     hex digit (4-f)  sets symbol table size to the 
  73.              specified value (in K bytes);
  74.              default is 8 (5 for versions x.xT.)
  75.     
  76.  
  77.     For example,
  78.         A>cc1 foobar.c -s6
  79.     supresses errors for undefined variables and sets 
  80.     symbol table size to 6K bytes;
  81.         A>cc1 zot.c -e
  82.     sets symbol table size to 14K bytes.
  83.     Note that the option list must contain no blanks.
  84.         A>cc1 b:td.c
  85.     takes the source file from disk B and writes the .CCI
  86.     file to disk B (regardless of what the currently logged
  87.     disk is.)
  88.  
  89.     On an 8080, speed is about 12 lines source/sec.
  90.  
  91. :Overview -- C Compiler, Pass 2
  92.  
  93. CC2:    This is the second half of the compiler. CC2 accepts
  94.     a ".CCI" file as input, and writes out a ".CRL" file
  95.     if no errors are detected. (CRL is mnemonic for
  96.     'C ReLocatable')
  97.  
  98.     If all goes well, writing out of the CRL file is
  99.     followed by deletion of the "CCI" file, and 
  100.     compilation is complete.
  101.  
  102.     As for CC1, if a disk is specified explicitly as in
  103.         A>cc2 c:yahoo
  104.     then the .CCI file is loaded from the specified disk
  105.     and the .CRL file is written to that same disk.
  106.  
  107.     On an 8080, execution time =  about 35 lines/sec.
  108.  
  109. :Overview -- C Linker
  110.  
  111. CLINK:    This program links a "main" function from some
  112.     CRL file together with C.CCC (for common system
  113.     subroutines) and any subordinate functions which
  114.     "main" may require (from perhaps many CRL files).
  115.  
  116.     A successful linkage causes a ".COM" file to be
  117.     generated. At this point, the 8080 absolute
  118.     machine code file is ready to be executed (for
  119.     better or worse) as a transient command by CP/M.
  120.  
  121.     The first argument on the command line must be the
  122.     name of a CRL file containing a "main" function. If
  123.     the name is specified with an extension, then that
  124.     extension is interpreted specially as indicating
  125.     which disks are to be involved in the operation (this
  126.     is akin to the mechanism ASM uses to determine source
  127.     and destination disks.)
  128.  
  129.     For example, if the first argument to CLINK were
  130.     given as:
  131.         A>clink foo.bc
  132.     then CLINK would interpret the "b" in ".bc" as 
  133.     specifying the disk on which "DEFF.CRL" and "C.CCC" are
  134.     to be found, and the "c" in ".bc" as specifying which
  135.     disk the .COM file is to be written to. Both of these
  136.     values, if omitted, default to the currently logged in
  137.     disk.
  138.     The first argument may also be preceded by a disk
  139.     designation, to specify where all .CRL files are to be
  140.     searched for (by default). For example, the command
  141.         A>clink b:zot.ac
  142.     tells CLINK to get C.CCC and DEFF.CRL from disk A; to
  143.     write the ouput file to disk C; and to find ZOT.CRL on
  144.     disk B.
  145.  
  146.  
  147.     Any other CRL files to search may also be specified
  148.     on the command line (WITHOUT their .CRL suffixes),
  149.     causing those to be searched in the order specified.
  150.     The default disk to search will be the same disk from
  151.     which the original CRL file was taken; this default
  152.     can be overridden by specifying an explicit disk
  153.     designation for any appropriate CRL file name needing
  154.     it. For example,
  155.         A>clink c:foo.bb bar a:zot fraz
  156.     causes disk C to be searched for the files FOO.CRL,
  157.     BAR.CRL and FRAZ.CRL, while disk A would be searched
  158.     to find ZOT.CRL. Disk B is where CLINK would expect
  159.     DEFF.CRL and C.CCC to reside, and the output would go
  160.     to disk B also.
  161.  
  162.  
  163.     When all given CRL files have been searched, CLINK
  164.     will automatically search DEFF.CRL.
  165.  
  166.     If there are still some unresolved references, then
  167.     CLINK will ask for input from the keyboard to try
  168.     resolving them.
  169.  
  170.     There are also several options which may be
  171.     specified on the command line. Each option must
  172.     be preceded by a dash (-); the space between
  173.     options and their argument (if needed) is optional.
  174.     The presently supported options are:
  175.  
  176.     -s        Prints out load statistics;
  177.     -t nnnn        Reserves location nnnn (hex) and
  178.             above for user; default is to 
  179.             reserve no space. What this really
  180.             does is to cause the first op in
  181.             the object file to be
  182.                 lxi sp,nnnn
  183.             instead of
  184.                 lxi sp,bdos.
  185.     -o name        Causes the .COM file generated to
  186.             have the given name. Default is 
  187.             the name of the first .CRL file
  188.             given (the one with the "main"
  189.             function.)
  190.  
  191.     -e xxxx        Sets start of data area to address
  192.             xxxx, to maintain consistency between
  193.             several separate .COM files when
  194.             chaining (via the library function
  195.             "exec") is used.
  196.     -c        Specifies that the .COM file is to
  197.             be chained to from another .COM file.
  198.             If the resultant .COM file is invoked
  199.             directly from CP/M instead of via the
  200.             "exec" function, then ARGC & ARGV
  201.             processing is suspended, since upon
  202.             being chained to you wouldn't want
  203.             ARGC & ARGV processing to take place.
  204.                 Note that if you use this
  205.             option, you should also use the -e
  206.             option to set the data area address
  207.             equal to that of the chaining .COM
  208.             file.
  209.     
  210.  
  211.  
  212.     Examples:
  213.         A>clink foo bar
  214.     gets "main" from the file FOO.CRL, searches for
  215.     needed functions first in FOO.CRL and then, if needed,
  216.     in BAR.CRL and DEFF.CRL. All files are assumed to 
  217.     reside on the currently logged in disk.
  218.  
  219.         A>clink b:ihtfp belle -s
  220.     searches for IHTFP.CRL and BELLE.CRL on disk B; prints
  221.     a statistics summary when linkage is complete. The 
  222.     files DEFF.CRL and C.CCC are assumed to reside on the
  223.     currently logged in disk; output also goes to the
  224.     currently logged in disk.
  225.  
  226.         A>clink b:ihtfp.aa -s belle -o zot
  227.     is the same as the last example except: the output
  228.     file is called ZOT.COM, DEFF.CRL and C.CCC are assumed
  229.     to reside on A, and output goes to A.
  230.  
  231.  
  232.         A>clink stoned -t7000 -s
  233.     sets top of memory to 7000h and prints out load
  234.     statistics. Current disk used for everything.
  235.  
  236.     Note that if the load statistics tell you that
  237.     the "LAST ADDRESS" is greater than the "TOP OF
  238.     MEMORY", the program hasn't got the chance of a
  239.     snowball in hell of running correctly.
  240.  
  241. :Oveview -- C Librarian
  242.  
  243. CLIB:    This program maintains .CRL files, allows transfer
  244.     of functions from one CRL file to another, etc. To
  245.     invoke CLIB, just type 
  246.             A>clib
  247.     Clib will print a line such as
  248.         FUNCTION BUFFER SIZE = nnnnn
  249.     specifying the largest function size that can be
  250.     handled. Attempting to "transfer" or "extract" a 
  251.     function larger than this size could be destructive.
  252.  
  253.     Next CLIB will prompt with a "*". Typing "h" at 
  254.     this point will give you a command summary.
  255.  
  256.     Basically, you work CLIB by opening one to six
  257.     CRL files (which then become associated with    
  258.     "file numbers"), diddling the files to your hearts
  259.     content, closing all files which you altered, and
  260.     typing control-C.
  261.  
  262.  
  263.     The old version of any CRL file you change with CLIB
  264.     is renamed to name.BRL (for Backup ReLative).
  265.  
  266.     A sample session of CLIB to, say, transfer the 
  267.     functions named "FOO", "BAR", and "ZOT" from
  268.     a .CRL file named "DSSR" to one named "RTS" would
  269.     go as follows:
  270.  
  271.  
  272.     A>clib
  273.  
  274.     BD SOFTWARE C LIBRARIAN VERSION x.x
  275.     FUNCTION BUFFER SIZE = xxxx BYTES
  276.  
  277.     * open 0 dssr
  278.     * open 1 rts
  279.     * t 0 1 foo
  280.     * t 0 1 bar
  281.     * t 0 1 zot
  282.     * c 1
  283.     * ^C
  284.  
  285.     A> ...
  286.  
  287.  
  288.     The "open" commands prepare to do work on a .CRL file,
  289.     and associate each .CRL file opened with a digit (0-5).
  290.     The "transfer" commands tell CLIB to transfer the
  291.     named function from the first file (named by file #)
  292.     to the second file (also named by number).
  293.     The "close" command need only be given for files
  294.     which have been altered; since DSSR wasn't written
  295.     to in the above example, it didn't need to be closed,
  296.     but RTS did need to be closed.
  297.  
  298.  
  299. DEFF.CRL:  This file contains the standard function library...
  300.        all 60+ functions worth. See the BDS C User's Guide
  301.        for documentation on these functions.
  302. :Overview -- C Skeleton File
  303.  
  304. C.CCC:    The run-time skeleton file, containing code for
  305.     processing the command line (generating argc and
  306.     argv, for you UNIX lovers), room for file I/O
  307.     buffers, some math subroutines, etc.
  308.  
  309.  
  310.  
  311.     Note on the BDS C compiler:
  312.  
  313.     THIS IS NOT AN INTERPRETER.
  314.  
  315.     Some hacks, such as BASIC-E, are billed as compilers
  316.     but actually just do some preprocessing and then
  317.     interpret the program. BDS C is a true compiler,
  318.     generating not-too-optimal but nevertheless quick
  319.     8080 code.
  320.  
  321.     For the gory details on the BDS C implementation, see
  322.     my notes to APPENDIX A of the EXCELLENT book  
  323.         "The C Programming Language."
  324.  
  325. :Variable Types
  326.  
  327.     Variable types supported:
  328.     int     char    unsigned    struct    union
  329.     arrays (of one or two dimensions)
  330.     pointers
  331.     simple combinations of the above
  332.  
  333.     For example,
  334.             char *foo[10][15];
  335.     declares foo to be a two dimensional array of
  336.     pointers to characters;
  337.  
  338.             char (*foo)();
  339.     declares foo to be a pointer to a function returning
  340.     a character;
  341.  
  342.             char *foo, bar, zot[10];
  343.     declares foo to be a pointer to characters, bar to
  344.     be a single char variable, ant zot to be an array
  345.     of 10 characters.
  346.  
  347. :Braces
  348.  
  349.     If your keyboard doesn't support the '{' and '}'
  350.     characters (open and close brace, for those of
  351.     you whose printer doesn't know about ascii 7B and
  352.     7D), the symbols 'begin' and 'end' may be 
  353.     substituted. Don't unless you have to; '{' and '}'
  354.     take up less memory.
  355.     The CONVERT program will perform this conversion,
  356.     if necessary.
  357.  
  358. :Variable Accessing
  359.  
  360.     Since all functions in C may be used recursively, all
  361.     variable accessing is done relative to a base-of-
  362.     stack-frame pointer, kept in the BC register pair
  363.     during execution. Note that it takes 8 bytes of code
  364.     to transfer a simple local variable whose address is
  365.         (Base of stack pointer) + foo
  366.     to the HL register pair; The code appears as:
  367.  
  368.         lxi h,foo
  369.         dad b
  370.         mov a,m
  371.         inx h
  372.         mov h,m
  373.         mov m,a .
  374.     To get an array element or structure element is even
  375.     more hairy. Facts like this are enough to make me 
  376.     REALLY wish Intel had bothered to implement a double
  377.     byte indirect load instruction. Oh well.
  378.  
  379. :ARIES-1 C Library
  380.  
  381.      The  following  are the names of the routines available in the  C 
  382. Library DEFF.CRL.   They are listed here as a memory convenience,  and 
  383. refer to the manual for further details.
  384.  
  385. 1.  General Purpose Functions
  386.  
  387.      csw()          exit()         bdos(c,de)          peek(n)
  388.      poke(n,b)      inp(n)         outp(n,b)           pause()
  389.      sleep(n)       call(adr,h,a,b,d)                  abs(n)
  390.      srand(n)       rand()         setmem(adr,count,byte)
  391.      movmem(source,dest,count)     qsort(base,nel,width,compar)
  392.        char *source, *dest;          char *base; int(*compar)();
  393.      exec(name)
  394.        char *name;
  395.  
  396. 2.  Character Input/Output
  397.  
  398.      getchar()      ungetch(c)     kbhit()             putchar(c)
  399.      puts(str)      char *gets(str)
  400.        char *str;     char *str;
  401.      printf(format,arg1,arg2,...)  scanf(format,arg1,arg2,...)
  402.        char *format;                 char *format;
  403.  
  404. 3.  String and Character Processing
  405.  
  406.      isalpha(c)     isupper(c)     islower(c)     isdigit(c)
  407.        char c;        char c;        char c;        char c;
  408.      touppper(c)    tolower(c)     isspace(c)     strcat(s1,s2)
  409.        char c;        char c;        char c;        char *s1, *s2;
  410.      strcmp(s1,s2)  strcpy(s1,s2)  strlen(str)    atoi(str)
  411.       char *s1,*s2;  char *s1,*s2;  char *str;     char *str;
  412.      initw(array,string)           initb(array,string)
  413.        int *array; char *string;     char *array, *string;
  414.      getval(strptr)
  415.        char **strptr;
  416.  
  417. 4.  File I/O
  418.  
  419.      creat(filename)               unlink(filename)
  420.        char *filename;               char *filename;
  421.      open(filename,mode)           close(fd)
  422.        char *filename;
  423.        {mode=0 - input, mode=1 - output, mode=2 - input and output}
  424.      read(fd,buf,nbl)              write(fd,buf,nbl)
  425.        char *buf;                    char *buf;
  426.      seek(fd,offset,code)          tell(fd)
  427.      fopen(filename,iobuf)         fcreat(filename,iobuf)
  428.        char *filename;               char *filename;
  429.        struct buf *iobuf;            struct buf *iobuf;
  430.      getc(iobuf)                   putc(c,iobuf)
  431.        struct buf *iobuf;            char c; struct buf *iobuf;
  432.      getw(iobuf)                   putw(w,iobuf)
  433.        struct buf *iobuf;            struct buf *iobuf;
  434.      fflush(iobuf)
  435.        struct buf *iobuf;
  436.  
  437. 5.  Plotting Functions (for Memory-Mapped Video Boards)
  438.  
  439.      setplot(base,xsize,ysize)
  440.      clrplot()
  441.      plot(x,y,chr)
  442.        char chr;
  443.      txtplot(string,x,y,ropt)
  444.        char *string;
  445.      line(c,x1,y1,x2,y2)
  446.  
  447. 6.  Plotting Functions for Hazeltine 1500
  448.  
  449.      clear()
  450.      cplot(x,y,chr)
  451.        char chr;
  452.      ctxtplot(x,y,string)
  453.        char *string;
  454.  
  455. 7.  Special I/O -- CIO
  456.  
  457.      cio(fn) or cio(fn,arg)
  458.  
  459.           CIO indexes directly into the BIOS Jump Table.   'fn' is the 
  460. index offset,  and 'arg' is an argument passed (up to 16  bits).   The 
  461. offsets and functions permitted are --
  462.  
  463.      Offset    Function
  464.  
  465.        0       CONST -- Console status;  Returned value = 0 if no char 
  466.                  ready, 255 if char ready
  467.        1       CONIN -- Console input; Returned value = char typed
  468.        2       CONOUT -- Console output; Input value = char to output
  469.        3       LIST -- List output; Input value = char to output
  470.        4       PUNCH -- Punch output; Input value = char to output
  471.        5       READER -- Reader input; Returned value = char input
  472. :Special I/O using CIO
  473.  
  474.      CIO is called by --
  475.  
  476.                cio(fn) or cio(fn,arg)
  477.  
  478.      CIO indexes directly into the BIOS Jump Table.  'fn' is the index 
  479. offset,  and 'arg' is an argument passed (up to 16 bits).  The offsets 
  480. and functions permitted are --
  481.  
  482.      Offset    Function
  483.  
  484.        0       CONST -- Console status;  Returned value = 0 if no char 
  485.                  ready, 255 if char ready
  486.        1       CONIN -- Console input; Returned value = char typed
  487.        2       CONOUT -- Console output; Input value = char to output
  488.        3       LIST -- List output; Input value = char to output
  489.        4       PUNCH -- Punch output; Input value = char to output
  490.        5       READER -- Reader input; Returned value = char input
  491.