Clara-Doc - Programmer Reference

Module: CTBUFF

Methods

MethodDescription
CTBUFF_BuffCatConcatenates at CTBUFF instance to another CTBUFF instance.
CTBUFF_BuffCompCompares a CTBUFF instance to another CTBUFF instance.
CTBUFF_BuffSetInitializes a CTBUFF instance from another CTBUFF instance.
CTBUFF_ByteAtReturns the byte specified at a given location within the buffer.
CTBUFF_CatConcatenates a buffer at the end of the buffer's current value.
CTBUFF_CompCompares a CTBUFF instance to a byte string
CTBUFF_ConstructorCreates an instance of type CTBUFF.
CTBUFF_DestructorReleases the CTBUFF instance and its resourses.
CTBUFF_GetRetrieves the buffer's value.
CTBUFF_LengthReturns the size in bytes of the buffer's value.
CTBUFF_SearchReturns the index positions where a pattern is found within the buffer's value.
CTBUFF_SetInitializes the buffer with a value.
CTBUFF_SplitReturns a list of all strings delimited by a specified separator pattern.



Description

The CTBUFF class implements a byte buffer. A byte buffer is a string of bytes (not a string of characters, unless each character can be represented by a single byte). The usefulness of the CTBUFF class mainly resides in the fact that for practical purposes, it does not have a limit on its size (the size limit is system-dependent). Since it is a byte buffer, this means you can load an image or a video file into it. If you know for a fact that the buffer holds a character string, then the CTBUFF provides a conversion method from one CCSID to another using the standard iconv C runtime function (which can be tricky).
Creating and disposing CTBUFF instances
Before using a CTBUFF, a CTBUFF instance has to be created (constructed). This is done by calling the CTBUFF_Constructor method. A pointer to a CTBUFF instance will be returned to the caller. This pointer will be used in calls to other CTBUFF methods. Every time CTBUFF_Constructor is called, a new CTBUFF instance is created and accessible through the pointer that is returned. This allows for several CTBUFF instances within the same porgram. Be sure to pass the appropriate pointer when calling CTBUFF methods. Once a CTBUFF instance is no longer needed, its resources have to be reclaimed via a call the the CTBUFF_Destructor method (you must pass the pointer to the CTBUFF instance that will be garbage collected). Call the CTBUFF_Constructor method on every CTBUFF instance once they are no longer needed. In between calls to the constructor and the destructor for a given CTBUFF instance, you may call any CTBUFF method on that CTBUFF instance.
                                       
 /INCLUDE QINCSRC,CTBASE               
                                       
DRc               S             10I 0  
DpBuff            S               *    
                                       
 /Free                                 
                                       
    pBuff = CTBUFF_Constructor();      
                     
                     
    // Use CTBUFF instance via methods by using the pBuff pointer                                   
    //
    // ...
    
    
    // We are done and need to gargabe collect CTBUFF resources
    
    CTBUFF_Destructor(pBuff);          
                                       
    *InLR = *On;                       
    Return;                            
                                       
 /End-Free