home *** CD-ROM | disk | FTP | other *** search
/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / CPM / BDSC / BDSC-3 / V146.DOC < prev    next >
Text File  |  2000-06-30  |  13KB  |  260 lines
  1.  
  2.                           BDS C User's Guide Addenda
  3.                          v1.46 Edition --  March, 1982
  4.  
  5.                                   Leor Zolman
  6.                                   BD Software
  7.                                 33 Lothrop st.
  8.                         Brighton, Massachussetts 02135
  9.  
  10.  
  11.  
  12.      There  have  been  several new sets of features added to BDS C v1.46.  The
  13. new   features   fall   into  three   catagories:   preprocessor   enhancement,
  14. CP/M-specific compiler performance  enhancement by selective overwriting of the
  15. CCP (Console Command Processor), and  new  utility  programs (including CASM.C,
  16. which  provides for the creation of CRL-format object  files  out  of  assembly
  17. language  source  files WITHOUT the need for MAC.COM and the old CMAC.LIB macro
  18. package).  
  19.  
  20.  
  21. The preprocessor enhancements are as follows:  
  22.  
  23. 0.   Parameterized  #defines are now supported. This allows a macro in the form
  24.      of a function call  to  be expanded (before compilation) into an arbitrary
  25.      string, with the original  parameters  substituted  into  the string.  For
  26.      example, the sequence 
  27.      
  28.              #define foo(x,y) x * 3 + y
  29.              .
  30.              .
  31.              .
  32.              z = foo(bar,zot());
  33.  
  34.      results in the final line actually reading:  
  35.      
  36.              z = bar * 3 + zot();
  37.  
  38.  
  39. 0.5  One feature of "#define" substitution has been slightly changed:    when a
  40.      symbolic  constant appears in the definition of ANOTHER symbolic constant,
  41.      then the substitution  of the first constant does not take place until the
  42.      substitution of the second does. This means that in a sequence such as 
  43.      
  44.              #define FOO 1
  45.              #define BAR FOO+1
  46.  
  47.      the  string that gets substituted  for  "BAR"  depends  upon  the  current
  48.      definition  of  "FOO"; if "FOO" got re-#defined at some point, "BAR" would
  49.      change accordingly.  Given  the  above  example, in past versions of BDS C
  50.      "BAR" became "1+1" at its definition point and would not have changed even
  51.      if "FOO" were re-#defined, unless "BAR" was  also re-#defined after "FOO".
  52.  
  53. 1.   The 
  54.      
  55.              #if <expr>
  56.  
  57.      conditional  compilation  directive  is now supported,  but  only  with  a
  58.      special limited syntax for the expression argument, defined as follows:  
  59.      
  60.              <expr>  := <expr2>              or
  61.                         <expr2> && <expr>    or
  62.                         <expr2> || <expr>
  63.  
  64. BDS C v1.46 Doc Update, 3/82            1
  65.  
  66.  
  67.  
  68.           
  69.              <expr2> := <constant>           or
  70.                         !<expr2>             or
  71.                         (<expr>)
  72.  
  73.      The <constant> may be a symbolic constant,  but  is  treated  as a logical
  74.      value always...i.e, 0 is false and any non-zero value is true (1).    This
  75.      allows  users  to  write  system-dependent conditional expressions without
  76.      having to resort to #ifdef/#ifndef  and  commenting/un-commenting  #define
  77.      statements to yield the desired conditions.  
  78.  
  79. 2.   Nesting   of  conditional  compilation  directives  is  now  allowed,  and
  80.      incorrect nesting  attempts  will now draw an appropriate error instead of
  81.      doing random things to the source  text.    Note that each and every #else
  82.      directive  MUST  be  followed  by a matching #endif  (unlike  C's  control
  83.      structure syntax, in which an if...else  chain  may be extended as long as
  84.      desired.) 
  85.  
  86. ****************************
  87.  
  88.  
  89. The following enhancements to the v1.46 compiler and linker affect the USAGE of
  90. the compiler, not the C language syntax it accepts:  
  91.  
  92. In  the  past, the compiler and linker have performed a  CP/M  warm-boot  after
  93. every compilation  had  either  been completed or aborted due to an error.  For
  94. v1.46, a warm-boot will only take place when the memory occupied by the Console
  95. Command Processor (CCP) is actually needed for the task. Since there is usually
  96. plenty  of memory left over after  a  compilation  or  linkage,  I  decided  to
  97. eliminate  the  pain of having to wait for the system to re-boot after each and
  98. every usage of the compiler or linker.  
  99.  
  100. One feature of BDS  C  in  the  past has been that it automatically aborted any
  101. pending "SUBMIT" file after compilation  when an error had been detected during
  102. the compilation. This had required the compiler  to seek to the directory track
  103. on disk and erase "$$$.SUB" before re-booting, but  the  extra  time thus spent
  104. was  negligable  since  a seek to the low tracks was coming up soon  anyway  in
  105. order to do the warm-boot.   Now, since a warm-boot isn't standard anymore, and
  106. the compiler is often used without  being  in  a "submit" file, the compiler no
  107. longer AUTOMATICALLY aborts "submit" files following  an error.  The feature IS
  108. availalable, though, through the new "-x" option to CC1.  If  "-x"  is given on
  109. the  CC1 command line, then "submit" files will be aborted following an  error.
  110. Any time CC1 is used in a "submit" file, "-x" should appear on the command line
  111. in the  "submit" file. If CC1 is used stand-alone, then "-x" should not be used
  112. (it would  just  cause  some needless disk activity upon error.) MAKE A NOTE OF
  113. THE "-X" OPTION UNDER THE  CC1  OPTIONS  SECTIONS  OF  THE  BDS C USER'S GUIDE.
  114. Since CLINK is not aborted very often, it has not been given  a "-x" option and
  115. (as  in  previous  versions)  will  always  abort  pending "submit" files  when
  116. prematurely terminated.  
  117.  
  118. Note that both the compiler and linker now send a bell character (control-G) to
  119. the  user  console after completing a task in which one  or  more  errors  have
  120. occurred. This  is  to alert the user in the case of a premature completion and
  121. return to command level  (as  when  a fatal error is detected by the compiler),
  122. since  audible  warm-boots no longer serve  to  notify  the  user  of  compiler
  123. termination.  
  124.  
  125. ****************************
  126.  
  127.  
  128.  
  129. BDS C v1.46 Doc Update, 3/82            2
  130.  
  131.  
  132.  
  133. The  major  new  utility   program   included   with   v1.46   is   CASM.C,  an
  134. assembly-language-to-CRL     conversion     preprocessor.    CASM    takes    a
  135. specially-formatted assembly lanaguage source  file  having extension ".CSM" as
  136. input,  and  puts  out  an  ".ASM" file which may then be assembled  using  the
  137. standard CP/M assembler (ASM.COM),  to  eventually  produce a CRL-format object
  138. file. Note that sources to the assembly-language portion  of  the BDS C library
  139. are now provided as ".CSM" files instead of ".ASM" files, and a  "submit"  file
  140. named   "CASM.SUB"  has  been  provided  to  automate  the  entire  process  of
  141. "CSM"-to-"CRL"  conversion. A separate document detailing the operation of CASM
  142. is included with the BDS C v1.46 package.  
  143.  
  144. A new wild-card expansion utility, named WILDEXP.C, allows ambiguous file names
  145. to be specified on  the  command line to C-generated programs; then by a simple
  146. function call, the ambiguous  references  are expanded to include all filenames
  147. on  the  current  disk that match the specification.  Exceptions  may  also  be
  148. specified.  
  149.  
  150. A new utility named  NOBOOT.C is also included: when NOBOOT.COM is invoked upon
  151. a COM file produced by  the C compiler, it will make some magic changes so that
  152. the COM file no longer performs  a  warm-boot  after  completing execution. The
  153. changes involve forcing the run-time stack to begin BELOW  the  CCP, and having
  154. the program save the system stack pointer passed to it by CP/M so  that  the SP
  155. may be restored after execution and control can pass directly back to the  CCP.
  156. NOBOOT  should  be  used ONLY with programs linked using the standard, supplied
  157. form of the run-time package (C.CCC). Note that the "topofmem" library function
  158. has been modified to recognize when NOBOOT is in effect at run-time, and should
  159. return the correct value for the end of available user memory in all cases.  
  160.  
  161. ****************************
  162.  
  163.  
  164. The following bugs have been detected and corrected for BDS C v1.46:  
  165.  
  166. 1.   CC1 had crashed  when  an  "#include"  file  was  not  terminated  with  a
  167.      carriage-return/linefeed sequence.  
  168.  
  169. 2.   CLINK  no  longer  complains about not being able to find "DEFF3.CRL" when
  170.      there are undefined  function  references  in a linkage; if DEFF3.CRL does
  171.      exist, it will be searched, but if it does not  exist,  that  fact will no
  172.      longer draw an error.  
  173.  
  174. 3.   Literal  strings  having  continuation  lines might have confused the  CC1
  175.      preprocessor in some versions, to the effect that a "#defined" symbol name
  176.      that happened to match a character sequence  within  the continuation line
  177.      of  the  string  was incorrectly substituted for by the preprocessor,  and
  178.      such a symbol appearing  AFTER  the  end of the string was NOT substituted
  179.      for.  
  180.  
  181. 4.   In  the  DIO  package,  the variable "c" in  the  "getchar"  function  was
  182.      incorrectly declared as a  "char"  instead  of  an  "int";  this  caused a
  183.      physical EOF to be returned as the value 255 instead of -1. Note that this
  184.      problem  only  appeared  when the text file was not terminated by a CPMEOF
  185.      (control-Z) character.  
  186.  
  187. 5.   Another DIO-related bug: when  text  containing  both carriage-returns and
  188.      linefeeds  was  fed  to  the  DIO  "putchar" function, an  extra  linefeed
  189.      character was appended to each line  and  resulted  in an extra blank line
  190.      between  each  actual  line  of the output file. This has  been  fixed  by
  191.      building some state information  into the DIO version of "putchar" so that
  192.      the redundant linefeeds are not generated.  
  193.  
  194. BDS C v1.46 Doc Update, 3/82            3
  195.  
  196.  
  197.  
  198. 6.   CLINK now warns the user when the  address of the end of the external data
  199.      area falls above the effective "top  of  memory"  address  (and  thus  not
  200.      leaving any room for the run-time stack) to prevent hair-pulling confusion
  201.      if  such  a  condition  is not noticed by the user.  If you are generating
  202.      special-purpose code in which  you  purposely tell the linker that the top
  203.      of memory is below the external area,  then just ignore the error message.
  204.  
  205. 7.   The "gets" library function has been modified  to use the stack during its
  206.      BDOS  call  to  get  a  line of text, and then copy the  result  into  the
  207.      supplied buffer area. This  means  that  the  buffer area passed to "gets"
  208.      need no longer be 2 bytes longer than the longest  expected  string;  but,
  209.      "gets"  still  does not know how long the buffer you give it really is and
  210.      you must make sure to supply a large enough buffer (when "gets" calls BDOS
  211.      function 10, it supplies the BDOS with a 135-byte buffer on the stack, and
  212.      as much of this as is filled up is copied to the user-supplied buffer upon
  213.      return from the BDOS call).  
  214.  
  215.      A new alternative  to  "gets"  has  been supplied, called "getline", which
  216.      works just like the "getline" function  shown  in Kernighan & Ritchie. The
  217.      format is:  
  218.      
  219.              int getline(strbuf,maxlen)
  220.              char *strbuf;
  221.              int maxlen;
  222.  
  223.      "Getline" collects a line of text from the user, where the maximum allowed
  224.      length of the line is "maxlen" characters (where "maxlen" is supplied as a
  225.      parameter). The return value is the length of the  entered  line.    Since
  226.      "getline"  also uses BDOS function 10 to collect the line, a call such  as
  227.      "getline(str,135);"  would  work  the  same as "gets(str);". Use "getline"
  228.      either to limit the line length to some  small  number, or to allow longer
  229.      lines (up to 255 characters) than the maximum of  135  that "gets" allows.
  230.  
  231.      Note that both "gets" and "getline" will return immediatly  if  the number
  232.      of  characters  typed  reaches  the  maximum  allowed  (135  for "gets" or
  233.      'maxlen' for "getline"), even if no newline (carriage-return in this case)
  234.      is typed by the user. This is due to the behavior of the BDOS,  and  there
  235.      aint'  nuthin  to  be done about it short of writing an entire "gets" from
  236.      scratch in terms of low-level character I/O, and that just isn't worth the
  237.      trouble.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259. BDS C v1.46 Doc Update, 3/82            4
  260.