home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 18 / amigaformatcd18.iso / +look_here_1st!+ / af_on_the_web / websites / rwe / developer / blitz.doc next >
Text File  |  1997-07-03  |  24KB  |  818 lines
  1. TABLE OF CONTENTS
  2.  
  3. blitz.library/AddTokenUpdate
  4. blitz.library/AllocXtra
  5. blitz.library/DelTokenUpdate
  6. blitz.library/DetokeLine
  7. blitz.library/DetokeMem
  8. blitz.library/FindToken
  9. blitz.library/FreeBlitzLibs
  10. blitz.library/FreeTokeMem
  11. blitz.library/FreeXtra
  12. blitz.library/GetBlitzLibInfo
  13. blitz.library/GetFirstToken
  14. blitz.library/GetLineHeaderSize
  15. blitz.library/GetObjectMaximum
  16. blitz.library/GetObjectName
  17. blitz.library/GetVersion
  18. blitz.library/LoadBlitzLibs
  19. blitz.library/LoadFile
  20. blitz.library/LoadXtra
  21. blitz.library/LockBlitzLibs
  22. blitz.library/NewDetokeLine
  23. blitz.library/NumMaximums
  24. blitz.library/SaveXtra
  25. blitz.library/SetObjectMaximum
  26. blitz.library/SortTokens
  27. blitz.library/TokeLine
  28. blitz.library/TokeMem
  29. blitz.library/UnLockBlitzLibs
  30. blitz.library/AddTokenUpdate                       blitz.library/AddTokenUpdate
  31.  
  32.    NAME
  33.        AddTokenUpdate -- install a notification hook for command-library updates.
  34.  
  35.    SYNOPSIS
  36.        AddTokenUpdate(functionPtr);
  37.                       A0
  38.  
  39.    FUNCTION
  40.        This command lets you automatically have a function called whenever the
  41.        blitz command libraries are updated (i.e. calls to FreeBlitzLibs(),
  42.        LoadBlitzLibs() etc).
  43.  
  44.        Any registers may be treated as scratch registers.
  45.  
  46.    INPUTS
  47.        functionPtr - address of routine to call
  48.  
  49.    RESULT
  50.        NONE
  51.  
  52.    BUGS
  53.        A maximum of 16 notification hooks can be installed. No checking is
  54.        performed to ensure that the limit is not exceeded.
  55.  
  56.    SEE ALSO
  57.        DelTokenUpdate()
  58.  
  59. blitz.library/AllocXtra                            blitz.library/AllocXtra
  60.  
  61.    NAME
  62.        AllocXtra -- allocate and initialise a valid BlitzXtra structure.
  63.  
  64.    SYNOPSIS
  65.        xtraFile = AllocXtra();
  66.        D0
  67.  
  68.        struct BlitzXtra * AllocXtra(VOID);
  69.  
  70.    FUNCTION
  71.        This command allocates a new BlitzXtra structure, filling fields
  72.        with default values.
  73.  
  74.    INPUTS
  75.        NONE
  76.  
  77.    RESULT
  78.        xtraFile - an initialized BlitzXtra structure, or NULL on failure.
  79.  
  80.    SEE ALSO
  81.        FreeXtra(), <libraries/blitz.h>, <libraries/blitz.i>
  82.  
  83. blitz.library/DelTokenUpdate                       blitz.library/DelTokenUpdate
  84.  
  85.    NAME
  86.        DelTokenUpdate -- remove a previously created notification hook for
  87.                          command-library updates.
  88.  
  89.    SYNOPSIS
  90.        DelTokenUpdate(functionPtr);
  91.                       A0
  92.  
  93.    FUNCTION
  94.        This command removes a notification request, as created by a previous
  95.        call to AddTokenUpdate().
  96.  
  97.    INPUTS
  98.        functionPtr - address of routine to remove from notification list
  99.  
  100.    RESULT
  101.        NONE
  102.  
  103.    SEE ALSO
  104.        AddTokenUpdate()
  105.  
  106. blitz.library/DetokeLine                           blitz.library/DetokeLine
  107.  
  108.    NAME
  109.        DetokeLine -- detokenise a line containing valid tokenised Blitz source
  110.                      code.
  111.  
  112.    SYNOPSIS
  113.        success = DetokeLine(tokenSource,asciiDest);
  114.        D0                   A0          A1
  115.  
  116.        BOOL = DetokeLine(char * tokenSource, char * asciiDest);
  117.  
  118.    FUNCTION
  119.        This command will convert a line containing tokenised source into its
  120.        detokenised equivalent, placing the resulting string in the destination
  121.        buffer.
  122.  
  123.    INPUTS
  124.        tokenSource - a pointer to a line containing tokenised source
  125.                      (NOTE: the line should not contain any headers)
  126.  
  127.        asciiDest - a pointer to a line buffer where the detokenised line is to
  128.                    be placed
  129.  
  130.    RESULT
  131.        success - indication of success or failure
  132.  
  133.    NOTES
  134.        asciiDest should be at least 128 bytes in size. This routine will not
  135.        create a detokenised string of more than 128 bytes.
  136.  
  137. blitz.library/DetokeMem                            blitz.library/DetokeMem
  138.  
  139.    NAME
  140.        DetokeMem -- detokenise a block of memory containing valid tokenised
  141.                     Blitz source code.
  142.  
  143.                     ** THIS FUNCTION IS NOT YET IMPLEMENTED **
  144.  
  145.    SYNOPSIS
  146.        success = DetokeMem(tokenSource,asciiDest,length);
  147.        D0                  A0          A1        D0
  148.  
  149.        BOOL = DetokeLine(char * tokenSource, char * asciiDest, ULONG length);
  150.  
  151.    FUNCTION
  152.        This function will detokenise a block of memory into its detokenised
  153.        ASCII equivalent, placing the resultant data in the destination buffer.
  154.  
  155.    INPUTS
  156.        tokenSource - a pointer to a block of memory containing tokenised source
  157.  
  158.        asciiDest - a pointer to the destination ASCII buffer. This must be at
  159.        least as big as numlines * 128 in size
  160.  
  161.        length - the size of the source block
  162.  
  163.    RESULT
  164.        success - indication of success or failre
  165.  
  166.    NOTES
  167.        ** THIS FUNCTION IS NOT YET IMPLEMENTED **
  168.  
  169. blitz.library/FindToken                             blitz.library/FindToken
  170.  
  171.    NAME
  172.        FindToken -- retrieve the location inside the Blitz command libraries
  173.                     of a given token.
  174.  
  175.    SYNOPSIS
  176.        tokenptr = FindToken(token);
  177.        A3                   D0:16
  178.  
  179.        struct BlitzToken * tokenptr = FindToken(UWORD token);
  180.  
  181.    FUNCTION
  182.        This function will traverse the Blitz command libraries. If the given
  183.        token is found, the address of the token is returned - else a standard
  184.        ERROR token.
  185.  
  186.    INPUTS
  187.        token - a 2 byte token number
  188.  
  189.    RESULT
  190.        tokenptr - a pointer to the token (or an ERROR token)
  191.  
  192. blitz.library/FreeBlitzLibs                         blitz.library/FreeBlitzLibs
  193.  
  194.    NAME
  195.        FreeBlitzLibs -- free memory allocated to Blitz libraries
  196.  
  197.    SYNOPSIS
  198.        FreeBlitzLibs();
  199.  
  200.    FUNCTION
  201.        This function will free memory allocated by a previous call to
  202.        LoadBlitzLibs()
  203.  
  204.    INPUTS
  205.        NONE
  206.  
  207.    RESULT
  208.        NONE
  209.  
  210.    NOTES
  211.        This call may fail if the Blitz libraries are currently locked.
  212.        Programs which installed a notification hook will NOT be notified of
  213.        this change, and are removed from the notification list.
  214.  
  215.        This function is typically only called by the librarie's Expunge()
  216.        function, and not by applications.
  217.  
  218.    SEE ALSO
  219.        LoadBlitzLibs()
  220.  
  221. blitz.library/FreeTokeMem                           blitz.library/FreeTokeMem
  222.  
  223.    NAME
  224.        FreeTokeMem -- free memory allocated by a previous call to TokeMem()
  225.  
  226.    SYNOPSIS
  227.        FreeTokeMem(tokeMem);
  228.                    A0
  229.  
  230.    FUNCTION
  231.        This function will free any memory allocated by a call to TokeMem().
  232.  
  233.    INPUTS
  234.        tokeMem - a pointer to a block of tokenised source, as returned by the
  235.                  call to TokeMem()
  236.  
  237.    RESULT
  238.        NONE
  239.  
  240.    NOTES
  241.        It is necessary for an application to keep a track of values returned
  242.        by TokeMem() and similar functions, since the library does not perform
  243.        any garbage collection upon expunge.
  244.  
  245.    SEE ALSO
  246.        TokeMem()
  247.  
  248. blitz.library/FreeXtra                              blitz.library/FreeXtra
  249.  
  250.    NAME
  251.        FreeXtra -- free memory allocated by the functions AllocXtra() and
  252.                    LoadXtra()
  253.  
  254.    SYNOPSIS
  255.        FreeXtra(xtraFile);
  256.                 A0
  257.  
  258.        void FreeXtra(struct BlitzXtra * xtraFile);
  259.  
  260.    FUNCTION
  261.        This function will free any memory allocated by a call to AllocXtra()
  262.        or LoadXtra()
  263.  
  264.    INPUTS
  265.        xtraFile - a pointer to a valid BlitzXtra structure, as returned by
  266.                   either AllocXtra() or LoadXtra()
  267.  
  268.    RESULT
  269.        NONE
  270.  
  271.    NOTES
  272.        It is necessary for an application to keep a track of values returned
  273.        by AllocXtra(), LoadXtra() and similar functions, since the library does
  274.        not perform any garbage collection upon expunge.
  275.  
  276.    SEE ALSO
  277.        AllocXtra(), LoadXtra()
  278.  
  279. blitz.library/GetBlitzLibInfo                       blitz.library/GetBlitzLibInfo
  280.  
  281.    NAME
  282.        GetBlitzLibInfo -- fill out an applications BlitzLibComData structure with
  283.                           relevant information
  284.  
  285.    SYNOPSIS
  286.        success = GetBlitzLibInfo(comData);
  287.        D0                        A0
  288.  
  289.        BOOL success = GetBlitzLibInfo(struct BlitzLibComData * comData);
  290.  
  291.    FUNCTION
  292.        Following a call to LoadBlitzLibs(), the Blitz compiler requires certain
  293.        information around the structure of the libraries. This function fills out
  294.        a structure with this information.
  295.  
  296.    INPUTS
  297.        comData - a pointer to a previously created instance of a BlitzLibComData
  298.                  structure
  299.  
  300.    RESULT
  301.        success - an indication of success or failure
  302.  
  303.    NOTES
  304.        This routine is typically only required by the Blitz compiler
  305.  
  306.    SEE ALSO
  307.        LoadBlitzLibs(), <libraries/blitz.h>, <libraries/blitz.i>
  308.  
  309. blitz.library/GetFirstToken                         blitz.library/GetFirstToken
  310.  
  311.    NAME
  312.        GetFirstToken -- obtain the address of the first token in the library list
  313.  
  314.    SYNOPSIS
  315.        token = GetFirstToken();
  316.        D0
  317.  
  318.        struct BlitzToken * token = GetFirstToken(VOID);
  319.  
  320.    FUNCTION
  321.        This function returns the address of the first token in the library list,
  322.        as created by a previous call to LoadBlitzLibs()
  323.  
  324.    INPUTS
  325.        NONE
  326.  
  327.    RESULT
  328.        D0 - a pointer to the first token in memory, or NULL for failure
  329.  
  330.    SEE ALSO
  331.        LoadBlitzLibs(), FindToken()
  332.  
  333. blitz.library/GetLineHeaderSize                     blitz.library/GetLineHeaderSize
  334.  
  335.    NAME
  336.        GetLineHeaderSize -- get the size of the header prepended to Blitz source
  337.                             code
  338.  
  339.    SYNOPSIS
  340.        size = GetLineHeaderSize();
  341.        D0
  342.  
  343.        UWORD size = GetLineHeaderSize(VOID);
  344.  
  345.    FUNCTION
  346.        The standard Blitz line structure was fixed at 9 bytes. This consisted of
  347.        the usual Previous and Next pointers, as well as a byte indicating how
  348.        many characters are on the line. From v2.2 onwards, an extra control field
  349.        was inserted to allow procedure folding. To improve backwards compatibility
  350.        or programs it is necessary to know how large this header is. It can be
  351.        assumed that the following fields remain static :
  352.  
  353.            NEXT           0
  354.            PREVIOUS       4
  355.            NUMCHARS       HEADERSIZE-1
  356.            CHARS          HEADERSIZE
  357.  
  358.        This allows additional fields to be inserted without risking incompatibility
  359.        with older software.
  360.  
  361.    INPUTS
  362.        NONE
  363.  
  364.    RESULT
  365.        size - the number of bytes which make up the line header
  366.  
  367. blitz.library/GetObjectMaximum                      blitz.library/GetObjectMaximum
  368.  
  369.    NAME
  370.        GetObjectMaximum -- get the maximum number of instances for a given Blitz
  371.                            object
  372.  
  373.    SYNOPSIS
  374.        maximum = GetObjectMaximum(xtraFile, libNum);
  375.        D0                         A0        D0:16
  376.  
  377.        WORD maximum = GetObjectMaximum(struct BlitzXtra * xtraFile, UWORD libNum);
  378.  
  379.    FUNCTION
  380.        Each blitz library can have an associated 'object'. When compiling programs,
  381.        it is necessary for the compiler to allocate a fixed size object buffer. To
  382.        achieve this, a user-definable limit is set on the number of instances that
  383.        can be created for any given object. This information is stored in the
  384.        Blitz .xtra file. This function, when passed a valid library number and
  385.        BlitzXtra structure can return the maximum instances for the library's
  386.        associated object.
  387.  
  388.    INPUTS
  389.        xtraFile - a pointer to a valid BlitzXtra structure, as returned by a call
  390.                   to either AllocXtra() or LoadXtra()
  391.  
  392.        libNum   - the library's identification number
  393.  
  394.    RESULT
  395.        maximum - the maximum number of instances that can be created for the
  396.                  library's associated object (-1 indicated that no object
  397.                  is associated with the given library)
  398.  
  399.    SEE ALSO
  400.        GetObjectName(), AllocXtra(), LoadXtra(), <libraries/blitz.h>,
  401.        <libraries/blitz.i>
  402.  
  403. blitz.library/GetObjectName                         blitz.library/GetObjectName
  404.  
  405.    NAME
  406.        GetObjectName -- get the name for a library's associated object
  407.  
  408.    SYNOPSIS
  409.        name = GetObjectName(xtraFile, libNum);
  410.        D0                   A0        D0:16
  411.  
  412.        char * name = GetObjectName(struct BlitzXtra * xtraFile, UWORD libNum);
  413.  
  414.    FUNCTION
  415.        Each blitz library can have an associated 'object'. Each object has a unique
  416.        name, which is used when a programmer wishes to access a particular instance
  417.        of the object, or adjust the maximum instances of the object. This function
  418.        returns the name of the object associated with the given library.
  419.  
  420.    INPUTS
  421.        xtraFile - a pointer to a valid BlitzXtra structure, as returned by a call
  422.                   to either AllocXtra() or LoadXtra()
  423.  
  424.        libNum   - the library's identification number
  425.  
  426.    RESULT
  427.        name - a pointer to the object's name (or NULL if the library does not
  428.               have an associated object)
  429.  
  430.    BUGS
  431.        The memory used to return the string is shared. This means that
  432.        should two applications call this function together, the result is
  433.        unpredictable
  434.  
  435.    SEE ALSO
  436.        GetObjectMaximum(), AllocXtra(), LoadXtra(), <libraries/blitz.h>,
  437.        <libraries/blitz.i>
  438.  
  439. blitz.library/GetVersion                            blitz.library/GetVersion
  440.  
  441.    NAME
  442.        GetVersion -- obtain a string indicating the version of the library
  443.  
  444.    SYNOPSIS
  445.        version = GetVersion();
  446.        D0
  447.  
  448.        char * version = GetVersion(VOID);
  449.  
  450.    FUNCTION
  451.        This function simply returns the version of the library as a string.
  452.  
  453.    INPUTS
  454.        NONE
  455.  
  456.    RESULT
  457.        version - a pointer to a null terminated version string
  458.  
  459.    NOTES
  460.        This function is primarily designed to be called by SuperTED - enabling
  461.        the version of the compiler to be adjusted.
  462.  
  463.        Do NOT modify the contents of the string - make a copy if you need to
  464.  
  465. blitz.library/LoadBlitzLibs                         blitz.library/LoadBlitzLibs
  466.  
  467.    NAME
  468.        LoadBlitzLibs -- load available Blitz libraries from disk
  469.  
  470.    SYNOPSIS
  471.        success = LoadBlitzLibs();
  472.        D0
  473.  
  474.        BOOL success = LoadBlitzLibs(VOID);
  475.  
  476.    FUNCTION
  477.        This function will allocate memory for and read all available command
  478.        libraries from disk. The token and library tables are created. If the
  479.        libraries have already been loaded by a previous call, then this
  480.        function effectively does nothing.
  481.  
  482.    INPUTS
  483.        NONE
  484.  
  485.    RESULT
  486.        success - an indication of success or failure
  487.  
  488.    NOTES
  489.        This function will fail if the libraries have been locked.
  490.  
  491.    SEE ALSO
  492.        FreeBlitzLibs()
  493.  
  494. blitz.library/LoadFile                              blitz.library/LoadFile
  495.  
  496.    NAME
  497.        LoadFile -- load a source code file into memory
  498.  
  499.    SYNOPSIS
  500.        filePtr = LoadFile(fileName);
  501.        D0                 A0
  502.  
  503.        struct BlitzFile * filePtr = LoadFile(char * fileName);
  504.  
  505.    FUNCTION
  506.        This function will load a file into memory. Memory required to store the
  507.        file is allocated by this function. This function can read ASCII files
  508.        as well as the standard Blitz tokenised source files. Tokenisation is
  509.        performed if required.
  510.  
  511.    INPUTS
  512.        fileName - a pointer to a null-terminated string holding the name of the
  513.                   file to load
  514.  
  515.    RESULT
  516.        filePtr - a pointer to a BlitzFile structure (or NULL for failure)
  517.  
  518. blitz.library/LoadXtra                              blitz.library/LoadXtra
  519.  
  520.    NAME
  521.        LoadXtra -- load a source file's .xtra file into memory
  522.  
  523.    SYNOPSIS
  524.        xtraFile = LoadXtra(fileName);
  525.        D0                  A0
  526.  
  527.        struct BlitzXtra * xtraFile = LoadXtra(char * fileName);
  528.  
  529.    FUNCTION
  530.        This function will allocate memory for and load into this memory a Blitz
  531.        .xtra file.
  532.  
  533.    INPUTS
  534.        fileName - a pointer to a null-terminated string holding the name of the
  535.                   .xtra file to load
  536.  
  537.    RESULT
  538.        xtraFile - a pointer to the associated BlitzXtra structure (or NULL for
  539.                   failure)
  540.  
  541.    NOTES
  542.        No checking is made to ensure that the file passed is a valid .xtra file
  543.  
  544. blitz.library/LockBlitzLibs                         blitz.library/LockBlitzLibs
  545.  
  546.    NAME
  547.        LockBlitzLibs -- prevent access or modification to the Blitz command
  548.                         libraries in memory
  549.  
  550.    SYNOPSIS
  551.        success = LockBlitzLibs(accessMode);
  552.        D0                      D0
  553.  
  554.        BOOL success = LockBlitzLibs(WORD accessMode);
  555.  
  556.    FUNCTION
  557.        This function, given the appropriate access mode, will lock the Blitz
  558.        command libraries to prevent another task from either :
  559.  
  560.        a) Accessing them
  561.        b) Modifying them
  562.  
  563.    INPUTS
  564.        accessMode - a valid access mode. Can be one of either :
  565.  
  566.                 LIBS_ACCESS_EXCLUSIVE
  567.                 LIBS_ACCESS_READ
  568.  
  569.    RESULT
  570.        success - TRUE or FALSE if the lock was successful. FALSE indicates either :
  571.  
  572.                 An EXCLUSIVE lock was present
  573.                 A READ lock was present and you requested an EXCLUSIVE lock
  574.  
  575.    BUGS
  576.        No validation is performed on the accessMode. Therefore, invalid accessModes
  577.        will result in unpredictable behaviour
  578.  
  579.    SEE ALSO
  580.        UnlockBlitzLibs()
  581.  
  582. blitz.library/NewDetokeLine                         blitz.library/NewDetokeLine
  583.  
  584.    NAME
  585.        NewDetokeLine -- an experimental command design to make line detokenisation
  586.                         more flexible
  587.  
  588.    SYNOPSIS
  589.        success = NewDetokeLine(srcToken, destNonToken, destToken);
  590.        D0                      A0        A1            A2
  591.  
  592.        BOOL success = NewDetokeLine(char * srcToken, char * destNonToken, 
  593.                                     char * destToken);
  594.  
  595.    FUNCTION
  596.        This function is a prototype command designed to be used by the new version
  597.        of SuperTED, currently in development. In order to speed up the text displays,
  598.        a new approach to detoking lines was developed. The tokenised source line
  599.        is detoked into two buffers - one containing non-token source, the other
  600.        containing token-source (the latter which should be displayed in a 'special'
  601.        colour).
  602.  
  603.        For example :
  604.  
  605.             NPrint "This is a Test" : MouseWait
  606.  
  607.        would be detokenised to :
  608.  
  609.                    "This is a test" :                      ; non-token source
  610.             NPrint                    MouseWait            ; token source
  611.  
  612.    INPUTS
  613.        srcToken - a pointer to the NULL terminated tokenised line of source code
  614.  
  615.        destNonToken - a pointer to the buffer to be used to store non-token source
  616.  
  617.        destToken - a pointer to the buffer to be used to store token source
  618.  
  619.    RESULT
  620.        success - an indication of the commands success. This function will return
  621.                  FALSE if the command libraries have not been loaded.
  622.  
  623.    NOTES
  624.        Since this function is in prototype stage, it is not recommended that
  625.        application developers use this function.
  626.  
  627. blitz.library/NumMaximums                           blitz.library/NumMaximums
  628.  
  629.    NAME
  630.        NumMaximums -- return the number of objects in the library list
  631.  
  632.    SYNOPSIS
  633.        nummaxs = NumMaximums();
  634.        D0
  635.  
  636.        UINT nummaxs = NumMaximums(VOID):
  637.  
  638.    FUNCTION
  639.        Although slightly misleading by name, this function will return the total
  640.        number of objects associated with the various Blitz command libraries.
  641.  
  642.    INPUTS
  643.        NONE
  644.  
  645.    RESULT
  646.        nummaxs - the number of objects in the library list
  647.  
  648.    BUGS
  649.        At preset (v2.2) this command ignores the Lock status of the libraries.
  650.  
  651. blitz.library/SaveXtra                              blitz.library/SaveXtra
  652.  
  653.    NAME
  654.        SaveXtra -- save a .xtra file to disk
  655.  
  656.    SYNOPSIS
  657.        success = SaveXtra(fileName, xtraFile);
  658.        D0                 A0        A1
  659.  
  660.        BOOL success = SaveXtra(char * fileName, struct BlitzXtra * xtraFile);
  661.  
  662.    FUNCTION
  663.        This function will save a valid BlitzXtra structure to disk in the form
  664.        of a standard Blitz .xtra file.
  665.  
  666.    INPUTS
  667.        fileName - a null-terminated string containing the name of the .xtra file
  668.                   to save
  669.  
  670.        xtraFile - a pointer to a valid BlitzXtra structure
  671.  
  672.    RESULT
  673.        success - an indication of success or failure
  674.  
  675.    SEE ALSO
  676.        AllocXtra(), FreeXtra(), LoadXtra(), <libraries/blitz.h>, <libraries/blitz.i>
  677.  
  678. blitz.library/SetObjectMaximum                      blitz.library/SetObjectMaximum
  679.  
  680.    NAME
  681.        SetObjectMaximum -- set the maximum number of instances for a library's
  682.                            associated object
  683.  
  684.    SYNOPSIS
  685.        SetObjectMaximum(libNum, xtraFile);
  686.                         D0:16   A0
  687.  
  688.        void SetObjectMaximum(UINT libNum, struct BlitzXtra * xtraFile);
  689.  
  690.    FUNCTION
  691.        Similar in operation to GetObjectMaximum(), this function will set the
  692.        limit.
  693.  
  694.    INPUTS
  695.        libNum - the library ID which the object is associated with
  696.  
  697.        xtraFile - a pointer to a valid BlitzXtra structure
  698.  
  699.    RESULT
  700.        NONE
  701.  
  702.    SEE ALSO
  703.        GetObjectMaximum()
  704.  
  705. blitz.library/SortTokens                            blitz.library/SortTokens
  706.  
  707.    NAME
  708.        SortTokens -- create a sorted list of all Blitz command tokens
  709.  
  710.    SYNOPSIS
  711.        SortTokens();
  712.  
  713.        void SortTokens(VOID);
  714.  
  715.    FUNCTION
  716.        This will create a sorted list of all Blitz comman tokens - used to improve
  717.        the speed of the tokenisation / detokenisation commands.
  718.  
  719.    INPUTS
  720.        NONE
  721.  
  722.    RESULT
  723.        NONE
  724.  
  725.    NOTES
  726.        This function is designed to be called by SuperTED, and is not intended for
  727.        general use by applications.
  728.  
  729. blitz.library/TokeLine                              blitz.library/TokeLine
  730.  
  731.    NAME
  732.        TokeLine() - tokenise a line of ASCII source into Blitz tokens
  733.  
  734.    SYNOPSIS
  735.        success/len = TokeLine(srcAscii, destBuffer);
  736.        D0      D1             A0        A1
  737.  
  738.        BOOL success = TokeLine(char * srcAscii, char * destBuffer);
  739.  
  740.    FUNCTION
  741.        This function takes a standard null terminated line of ASCII text and
  742.        attempts to produce a tokenised version of it.
  743.  
  744.    INPUTS
  745.        srcAscii - a null terminated string containing ASCII characters
  746.  
  747.        destBuffer - the destination buffer to store the tokenised source in
  748.  
  749.    RESULTS
  750.        success - an indication of whether the command was successful or not
  751.  
  752.        len - the length of the tokenised line
  753.  
  754.    NOTES
  755.        This command returns information in TWO registers, D0 and D1, and as
  756.        such the second argument can only be accessed by assembly code. C
  757.        programmers must calculate the length of the tokenised string themselves
  758.        (hunt for a 0 byte). This restriction may change in the future.
  759.  
  760.    SEE ALSO
  761.        TokeLine()
  762.  
  763. blitz.library/TokeMem                               blitz.library/TokeMem
  764.  
  765.    NAME
  766.        TokeMem - tokenise a block of text into Blitz tokens
  767.  
  768.    SYNOPSIS
  769.        tokeBlock = TokeMem(srcAscii,maxBlockSize);
  770.  
  771.        UINT = TokeMem(char * srcAscii, UINT maxBlockSize);
  772.  
  773.    FUNCTION
  774.        This command takes a block of ASCII text (with each line terminated by
  775.        a LF, ASCII code 10) and creates a block of tokenised lines. The length
  776.        of the block is specified in the function call.
  777.  
  778.    INPUTS
  779.        srcAscii - a pointer to a LF terminated block of ASCII text
  780.  
  781.        maxBlockSize - the size of memory to allocate to hold the tokenised text
  782.  
  783.    RESULT
  784.        tokeBlock - a pointer to the tokenised text block (or NULL for failure)
  785.  
  786.    SEE ALSO
  787.        DetokeMem()
  788.  
  789. blitz.library/UnLockBlitzLibs                       blitz.library/UnLockBlitzLibs
  790.  
  791.    NAME
  792.        UnLockBlitzLibs - release a lock on the Blitz command libraries
  793.  
  794.    SYNOPSIS
  795.        UnLockBlitzLibs();
  796.  
  797.        void UnLockBlitzLibs(VOID);
  798.  
  799.    FUNCTION
  800.        Following a successful call to LockBlitzLibs(), the application must
  801.        release the lock when access is not required. This should be done at the
  802.        earliest opportunity to enable access for other applications.
  803.  
  804.    INPUTS
  805.        NONE
  806.  
  807.    RESULT
  808.        NONE
  809.  
  810.    NOTES
  811.        This function does not attempt to check if the application already has
  812.        an open lock - care must be taken to ensure that calls to LockBlitzLibs()
  813.        and UnLockBlitzLibs() are paired.
  814.  
  815.    SEE ALSO
  816.        LockBlitzLibs()
  817.  
  818.