home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 032.lha / doc / draco.doc / drutil.ref < prev    next >
Text File  |  1987-05-16  |  12KB  |  305 lines
  1. XVII. Utility Routines
  2.  
  3.     File "util.g" contains a number of declarations relevant to utility
  4.     routines provided in the Draco run-time system. Some of these
  5.     declarations are specific to the system in use, others are more
  6.     general. The types declared are as follows:
  7.  
  8.     /* result from the string comparison routine: */
  9.  
  10.     COMPARISON = enum {
  11.         EQUAL,
  12.         LESS,
  13.         GREATER
  14.     }
  15.  
  16.     COMPARISON is returned by the 'chars' comparison routine explained below.
  17.  
  18.     The 'ioerror' language construct returns an unsigned number which
  19.     indicates the nature of the first un-reset error which has occurred on
  20.     the channel given (or on the standard input channel if no channel is
  21.     given). The possible values are indicated below. 'ioerror' resets the
  22.     channel to a no-error state (CH_OK).
  23.  
  24.     /* error codes returned by 'ioerror': */
  25.  
  26.     ushort
  27.         CH_OK = 0,        /* no error */
  28.  
  29.         CH_EOF = 1,     /* read past end-of-file indicator */
  30.         CH_CLOSED = 2,    /* use after close */
  31.  
  32.         CH_NONEXIS = 3,    /* file doesn't exist */
  33.         CH_DISKFULL = 4,    /* disk is full; write failed */
  34.  
  35.         CH_MISSING = 5,    /* no data on line */
  36.         CH_BADCHAR = 6,    /* bad character for input conversion */
  37.         CH_OVERFLOW = 7;    /* overflow on numeric conversion */
  38.  
  39.     Draco does not contain a proper 'string' datatype. Such a type requires
  40.     that 'string' variables be initialized before use, and that all
  41.     dynamically allocated storage be cleared. Alternatively, a garbage
  42.     collector is needed to reclaim the storage occupied by 'lost' strings.
  43.     Neither alternative is in keeping with the nature of Draco as a systems
  44.     programming language. Thus Draco uses C-style strings (called 'chars'
  45.     values) in which a string is a pointer to a sequence of characters
  46.     terminated by the special character '\e'. The following utility
  47.     routines are provided to aid in the use of 'chars' values (whose type
  48.     is *char, pointer to character).
  49.  
  50.     CharsLen(*char charsPtr)ulong
  51.  
  52.         This routine, when passed a 'chars' value (a pointer to a row
  53.         of characters, such as a string constant enclosed in quotes),
  54.         will return the number of characters in that value, up to but
  55.         not including the terminating '\e'. Thus, the space needed to
  56.         hold a complete copy of the value is one greater than the
  57.         number returned.
  58.  
  59.     CharsEqual(*char charsPtr1, charsPtr2)bool
  60.  
  61.         This routine returns 'true' if the two chars values passed are
  62.         equal, else returns 'false'.
  63.  
  64.     CharsCopy(*char destination, source)void
  65.  
  66.         The chars value 'source' is copied into the buffer pointed to by
  67.         'destination'. It is assumed that the destination buffer is long
  68.         enough. The '\e' terminator is also copied.
  69.  
  70.     CharsCmp(*char charsPtr1, charsPtr2)COMPARISON
  71.  
  72.         The two chars values are compared, and the result (EQUAL, LESS or
  73.         GREATER) indicates the first with respect to the second. The
  74.         comparison uses the standard character set, thus, in ASCII, upper
  75.         case letters sort before lower case letters.
  76.  
  77.     CharsConcat(*char destination, source)void
  78.  
  79.         The source chars value is appended to the destination chars
  80.         value. Again, it is assumed that the destination buffer is long
  81.         enough.
  82.  
  83.     CharsCopyN(*char destination, source; ulong count)void
  84.  
  85.         This routine is the same as 'CharsCopy' except that at most
  86.         'count' characters (including the terminating '\e') will be
  87.         placed into the destination buffer.
  88.  
  89.     CharsIndex(*char subject, object)int
  90.  
  91.         The chars value 'object' is searched for in chars value
  92.         'subject'. The value returned is the 0-origin index of the object
  93.         in the subject, or is -1 if the object is not found in the
  94.         subject.
  95.  
  96.     The following routines are of miscellaneous purposes:
  97.  
  98.     ConvTime(ulong seconds; *char buffer)void
  99.  
  100.         The value in 'seconds' is an absolute time relative to some fixed
  101.         base. It is converted to a standard printable form, as in
  102.         "Tue Jan 15 17:23:15 1987". A '\e' is appended to the end of
  103.         the string, so the pointed-to buffer must be at least 25
  104.         characters long.
  105.  
  106.     CurrentTime()ulong
  107.  
  108.         Returns the current time in seconds relative to some fixed date.
  109.         On the Amiga the fixed date is that used by AmigaDOS, i.e.
  110.         midnight on Jan 1, 1978.
  111.  
  112.     exit(int errorCode)void
  113.  
  114.         Many programs can encounter situations in which they simply
  115.         cannot continue executing. In such cases, a uniform method of
  116.         aborting the run is needed. In Draco, the standard routine
  117.         'exit' is available for this purpose. It returns to the host
  118.         operating system, indicating the nature of the error via
  119.         'errorCode'. By convention, errorCode = 0 indicates successful
  120.         execution.
  121.  
  122.     BlockMove(*byte destination, source; ulong count)void
  123.  
  124.         'count' bytes are copied from the source to the destination. This
  125.         routine will typically do the copy in the fastest way the CPU can
  126.         handle, and thus is preferred for large copies.
  127.  
  128.     BlockMoveB(*byte destination, source; ulong count)void
  129.  
  130.         'count' bytes are copied from the source to the destination. The
  131.         addresses are decremented, instead of incremented as in the
  132.         previous routine. Thus, the pointers should point to the last
  133.         byte in the two regions. This routine is used to move data up
  134.         in a buffer without destroying the data because of overlap.
  135.  
  136.     BlockFill(*byte destination; ulong count; byte b)void
  137.  
  138.         'count' bytes starting at 'destination' are filled with 'b'.
  139.         Again, for large fills, this routine will be faster than a loop
  140.         in Draco.
  141.  
  142.     The following routines are additional entries into the storage allocation
  143.     system used by the 'new' and 'free' language constructs.
  144.  
  145.     Malloc(ulong length)*byte
  146.  
  147.         A region of memory of size 'length' is allocated and a pointer to
  148.         it is returned. This routine is used when the size of the region
  149.         is not known at compile time, and 'new' cannot be used.
  150.  
  151.     Mfree(*byte region; ulong length)void
  152.  
  153.         This routine is used to free regions allocated by 'Malloc'. It
  154.         can also be used to free regions allocated by the 'new'
  155.         construct, but this is not recommended, for clarity's sake.
  156.  
  157.     MerrorSet(bool newFlag)void
  158.  
  159.         This routine allows the setting of the storage allocator's abort
  160.         enable flag. Normally, if the allocator cannot allocate a
  161.         requested region, it will abort the program. In some situations
  162.         this is not desireable. With a flag value of 'true', calls to
  163.         'Malloc' and the 'new' construct are allowed to return nil if
  164.         they cannot allocated storage. It is then the programmer's
  165.         responsibility to check ALL such results, and to handle them
  166.         appropriately. Passing a value of 'false' will re-enable the
  167.         automatic aborts if storage cannot be allocated.
  168.  
  169.     MerrorGet()bool
  170.  
  171.         This routine returns the current setting of the abort enable
  172.         flag. It can be used by a lower-level routine or package of
  173.         routines to restore the state expected by its caller.
  174.  
  175.     The following routines are additional entries in the I/O system. They
  176.     perform various functions that are difficult or inefficient to perform
  177.     using Draco's I/O constructs. The description of operator types
  178.     describes further entry points used for I/O of operator types.
  179.  
  180.     RawRead(channel input binary chin; *byte buffer; ulong len)ulong
  181.  
  182.         Up to 'len' bytes are read from the given channel into the given
  183.         buffer. The actual number of bytes read is returned.
  184.  
  185.     RawWrite(channel output binary chout; *byte buffer; ulong len)ulong
  186.  
  187.         Up to 'len' bytes are written from the given buffer to the given
  188.         output channel.  The actual number of bytes written is returned.
  189.  
  190.     LineRead(channel input text chan; *char buffer; ulong len)ulong
  191.  
  192.         Up to 'len' characters are read from the input channel and
  193.         stored into 'buffer'. The number that could actually have been
  194.         read from the input line is returned. The entire input line is
  195.         consumed.
  196.  
  197.     LineWrite(channel output text chan; *char buffer; ulong len)ulong
  198.  
  199.         'len' characters from 'buffer' are written as a text line to
  200.         the given channel. If an error occurred before completing the
  201.         operation, the returned length will be less than the passed one.
  202.  
  203.     TextAppend(channel output text chan)bool
  204.  
  205.         The text channel is set so that the next actual write will be
  206.         an append to the end of the file. This call should be made after
  207.         opening the channel and before any output to the channel. If
  208.         you want to do other seeking on a text channel, you can open a
  209.         text channel which writes through a procedure which writes to a
  210.         binary channel, and do the seeking on the binary channel. Seeks
  211.         on text channels are non portable because of varying ways of
  212.         representing lines and end-of-lines. TextAppend will return
  213.         'false' if something didn't work.
  214.  
  215.     SeekIn(channel input binary chin; ulong posn)bool
  216.  
  217.         The given input channel is adjusted so that the next byte read
  218.         will come from position posn. If that position is beyond the
  219.         end of the file, no change is made and 'SeekIn' returns
  220.         'false', else it returns 'true'. This routine can only be used
  221.         on channels attached to files.
  222.  
  223.     GetIn(channel input binary chin)ulong
  224.  
  225.         The position in the file of the next byte to be read is returned.
  226.  
  227.     GetInMax(channel input binary chin)ulong
  228.  
  229.         This routine returns the maximum seek position of the file, i.e.
  230.         the number of bytes in the file.
  231.  
  232.     RandomOut(channel output binary chout)void
  233.  
  234.         This routine enables random output on the attached file.
  235.         'SeekOut' cannot be used on a file for which it has not been
  236.         enabled. The reason for this is that of buffering - if random
  237.         output is enabled, the I/O system may have to read part of the
  238.         file into its buffer in order to insert written data at the
  239.         proper place. For normal, sequential I/O, this is never needed,
  240.         and the overhead can be avoided.
  241.  
  242.     SeekOut(channel output binary chout; ulong posn)bool
  243.  
  244.         Sets the given output channel, which must be attached to a
  245.         file, so that the next byte written will be at the given position
  246.         in the file.
  247.  
  248.     GetOut(channel output binary chout)ulong
  249.  
  250.         Returns the position at which the next byte would be written.
  251.  
  252.     GetOutMax(channel output binary chout)ulong
  253.  
  254.         Returns the current size of the file.
  255.  
  256.     FlushOut(channel output binary chout)void
  257.  
  258.         Causes the output buffer for the file associated with the given
  259.         channel to be flushed to disk. This can be useful when writing
  260.         debugging information to a file from a program which may crash.
  261.  
  262.     ReOpen(channel input binary chin; channel output binary chout)void
  263.  
  264.         The input channel must be attached to a file. The output channel
  265.         must not yet have been opened. The output channel is attached to
  266.         the same file as the input channel, and is enabled for random
  267.         access. This call is used to set up channels to allow mixed
  268.         random reads and writes to/from the same file. This is needed
  269.         for things like database programs. The output channel must be
  270.         closed before the input channel is.
  271.  
  272.     The following routines deal with accessing command line parameters.
  273.     (These are like C's 'argv' and 'argc' parameters to 'main'.)
  274.  
  275.     GetPar()*char
  276.  
  277.         The next command line parameter is returned as a chars value,
  278.         complete with terminating '\e'. If no parameters remain, then
  279.         'nil' is returned. Leading blanks or tabs will have been
  280.         stripped off.
  281.  
  282.     RescanPars()void
  283.  
  284.         The saved copy of the command line parameters is modified
  285.         so that following calls to GetPar will return the parameters,
  286.         starting again with the first parameter.
  287.  
  288.     The following routines are intended to provide a system-independent way
  289.     to create, destroy and rename disk files:
  290.  
  291.     FileCreate(*char name)bool
  292.  
  293.         The specified file is created. If the creation attempt fails,
  294.         false will be returned, else true is returned.
  295.  
  296.     FileDestroy(*char name)bool
  297.  
  298.         The specified file is erased. If the erasure fails, false is
  299.         returned, else true is returned.
  300.  
  301.     FileRename(*char oldName, newName)bool
  302.  
  303.         The file named by 'oldName' will be renamed to 'newName'. If
  304.         the attempt fails, false is returned, else true is returned.
  305.