6/15/72                                              SALLOC (III)





NAME            salloc -- string manipulation routines



SYNOPSIS        (get size in r0)

                jsr     pc,allocate



                (get source pointer in r0,

                destination pointer in r1)

                jsr     pc,copy



                jsr     pc,wc



                (all following instructions assume r1 contains pointer)



                jsr     pc,release



                (get character in r0)

                jsr     pc,putchar



                jsr     pc,lookchar

                (character in r0)



                jsr     pc,getchar

                (character in r0)



                (get character in r0)

                jsr     pc,alterchar



                (get position in r0)

                jsr     pc,seekchar



                jsr     pc,backspace

                (character in r0)



                (get word in r0)

                jsr     pc,putword



                jsr     pc,lookword

                (word in r0)



                jsr     pc,getword

                (word in r0)



                (get word in r0)

                jsr     pc,alterword



                jsr     pc,backword

                (word in r0)



                jsr     pc,length

                (length in r0)



                jsr     pc,position

                (position in r0)



                jsr     pc,rewind



                jsr     pc,create



                jsr     pc,fsfile



                jsr     pc,zero



DESCRIPTION     This package is a complete set of routines for

                dealing with almost arbitrary length strings of

                words and bytes.  The strings are stored on a

                disk file, so the sum of their lengths can be

                considerably larger than the available core.



                For each string there is a header of four words,

                namely a write pointer, a read pointer and point-

                ers to the beginning and end of the block con-

                taining the string.  Initially the read and write

                pointers point to the beginning of the string.

                All routines that refer to a string require the

                header address in r1.  Unless the string is de-

                stroyed by the call, upon return r1 will point to

                the same string, although the string may have

                grown to the extent that it had to be be moved.



                allocate obtains a string of the requested size

                and returns a pointer to its header in r1.



                release releases a string back to free storage.



                putchar and putword write a byte or word respec-

                tively into the string and advance the write

                pointer.



                lookchar and lookword read a byte or word respec-

                tively from the string but do not advance the

                read pointer.



                getchar and getword read a byte or word respec-

                tively from the string and advance the read

                pointer.



                alterchar and alterword write a byte or word re-

                spectively into the string where the read pointer

                is pointing and advance the read pointer.



                backspace and backword read the last byte or word

                written and decrement the write pointer.



                All write operations will automatically get a

                larger block if the current block is exceeded.

                All read operations return with the error bit set

                if attempting to read beyond the write pointer.



                seekchar moves the read pointer to the offset

                specified in r0.



                length returns the current length of the string

                (beginning pointer to write pointer) in r0.



                position returns the current offset of the read

                pointer in r0.



                rewind moves the read pointer to the current po-

                sition of the write pointer.



                create returns the read and write pointers to the

                beginning of the string.



                fsfile moves the read pointer to the current po-

                sition of the read pointer.



                zero zeros the whole string and sets the write

                pointer to the beginning of the string.



                copy copies the string whose header pointer is in

                r0 to the string whose header pointer is in r1.

                Care should be taken in using the copy instruc-

                tion since r1 will be changed if the contents of

                the source string is bigger than the destination

                string.



                wc forces the contents of the internal buffers

                and the header blocks to be written on disc.



FILES           The allocator is in /usr/llc/alloc/alloca.



                The archive /usr/llc/alloc/allocb contains the

                individual routines discussed above.



                alloc.d is the temporary file used to contain the

                strings.



SEE ALSO        --



DIAGNOSTICS     "error in copy" if a disk write error occurs dur-

                ing the execution of the copy instruction.  "er-

                ror in allocator" if any routine is called with a

                bad header pointer.  "Cannot open output file" if

                file alloc.d cannot be created or opened.  "Out

                of space" if there's no available block of the

                requested size or no headers available for a new

                block.



BUGS            --



OWNER           llc,rhm