Block Memory Functions This library contains functions and variables for accessing data in blocks of memory. A block consists of up to 65,535 contiguous bytes. This allows for the storage, retrieval, and manipulation of data exceeding the maximum array length of 255. These functions assume that a block is divided into equally sized segments of up to 255 bytes in length. Data in the block is accessed by copying data into and out of arrays with the same length as the segment size. A segment typically consists of a string field, which is used as a key, followed by a number of mixed type fields. For example, the segments in a variable table might be 9 bytes long, consisting of a 7 byte variable name string (6 characters plus a terminator), the variable type (at index 7) and the variable length (at index 8). Usage: at the beginning of the program use the directives #include #include #include #include The following application variables are defined: int blkbgn; Start address of the block. int blkend; End address of the block. int blklen: Size of Segments in the block. These variables must be assigned before calling any of the functions in this module. They may be reassigned at any time, allowing the program to access different blocks. Note: Although a block usually begins and ends on a 256 byte boundary, this is not required. int blkptr; Pointer to the next segment. This can be reset to blkbgn using the blkrst() function. To preserve the segment position, this value must be saved before reassigning to another block, then r estored when reassigning back to the original block. The following application functions are defined: blkset(c); Block Set: Fills entire block with character c, leaving block pointer at end of block. Should be called with an argument of 0, to initialize a block before use. blkrst(); Block Reset: Sets block pointer to first segment. This routine is called before populating a block with calls to the blkput function. blknxt(); Block Next: Moves the block pointer to the bext segment. If the block pointer is moved past the end of the block, or the segment length is set to 0, a value of #TRUE is returned. Otherwise, a value of #FALSE is returned. blkprv(); Block Previous: Moves block pointer backward by the segment length set by a prior blkseg call. If the block pointer is moved past the beginning of the block, or the segment length is set to 0, a value of #TRUE is returned. Otherwise, a value of #FALSE is returned. blkput(n ,&m); Block Put: Copies n bytes of array m to a block at the current pointer location, and moves block the pointer forward by the segment length set by a prior blkseg call. If the appended bytes would overflow the end of the block, no bytes are copied and a value of #FALSE is returned. Otherwise, the bytes are copied and a value of #TRUE is returned. Note: Sets dstlo and dsthi to blklo and blkhi prior to the copy, updates blklo and blkhi, then calls the memcpy function. blkget(n ,&m); Block Get: Copies n bytes from a block at the current pointer location to array m, and moves the pointer forward by the segment length set by a prior blkseg call. If the copied bytes would overflow the end of the block, no bytes are copied and a value #FALSE is returned. Otherwise, the bytes are copied and a value of #TRUE is returned. Note: Sets dstlo and dsthi to the address of m, srclo and srchi to blklo and blkhi prior to the copy, updates blkslo and blkshi, then calls the memcpy function. blkswp(n); Block Swap: Swaps n bytes of array m with the current block segment (pointed to by the block pointer. The block pointer is not changed. Requires a prior call to the memdst function specifying an array at least n bytes long, which is used for temporary storage. Note: Sets temp0 to n, copies blklo and blkhi to dstlo, and dsthi, and calls memswp. blkmem(n ,&m); Block Memory search: Search block for n byte long segment matching array m. If a matching segment is found, the value #TRUE is returned and the destination pointer is set to the address of the matching segment, allowing it to be overwritten with a subsequent memcpy call. Otherwise, the value #FALSE is returned. Note: Sets srclo and srchi to the address of m, dstlo and dsthi to the address of the matching segment, and temp0 to n. Does not change the block pointer. blkstr(n ,&s); Block String Search: Search block for n byte long segments beginning with string s. If a matching segment is found, the value 255 (true) is returned and the segment is copied to the array set by a prior memdst call. Otherwise, the value 0 (false) is returned. Note: Sets srclo and srchi to the address of the segment, temp0 to n, and copies dstlo and dsthi to temp1 and temp2. Does not change the block pointer. blksrt(&m); Block Sort: Sort segments in block by initial string, using array m as temporary storage. Segments are sorted in alphabetical order, with segment length set by a prior blkseg call, and sorting stops at the first segment that begins with an empty string (the first byte is 0), leaving the block pointer at that segment. Note: Uses the selection sort algorithm. Sets temp1 and temp2 to the address of array m. blkdst(); Block Destination: Sets the destination pointer to the block segment pointer. This is a utility function called by other functions in this module. Note: Sets dstlo and dsthi to blklo and blkhi. Note: This library expects the following functions to be defined setdst(&s); Set destination string pointer setsrc(&s); Set source string pointer and initialize index memcmp Compare memory memcpy Copy memory memsrc Set memory source and count strcml Compare string (alternate entry point) along with the zero page variable pairs srclo, srchi Source String Pointer dstlo, dsthi Destination String Pointer blklo, blkhi Block Pointer the static variable blkslo, blkshi Block Start Address blkelo, blkehi Block End Address blklen Block Segment Length as well as the transient variables temp0, temp1, temp2 Temporary storage