Clara-Doc - Method Reference
CTBUFF_Split
Description
Returns a list of buffers (in a CTBUFFLST instance) resulting from the extraction of all tokens held between a supplied separator pattern.
Prototype
DCTBUFF_Split...
D PR 3U 0
D@This * Value
D@Separator * Value
D@SepLen 10I 0 Value
D@Tokens * Value
Parameters
@This
| Type | Pointer (*) |
| Passing Mode | Value |
| Description | The address of a CTBUFF instance. The CTBUFF instance MUST be created via a call to the CTBUFF_Constructor method. |
@Separator
| Type | Pointer (*) |
| Passing Mode | Value |
| Description | The address of a separator pattern that delimits the tokens. A pattern is any sequence of bytes. This can be a character string, a single byte value or any other sequence of bytes. |
@SepLen
| Type | 10I 0 |
| Passing Mode | Value |
| Description | The length in bytes of the separator pattern. |
@Tokens
| Type | Pointer (*) |
| Passing Mode | Value |
| Description | A pointer to a CTBUFFLST instance. This instance must be provided (constructed) by the caller. |
Return Values
| Symbolic Constant | Value | Description |
| CS_SUCCESS | 0 | The method succeeded. |
Notes
The method will create a set of tokens from the CTBUFF instance value based on a separator pattern (a search string that separates requested tokens). The CTBUFF instance value will remain unchanged. For example, if a CTBUFF instance value contains carriage return/linefeeds, then specifying \r\n as a separator pattern will return all substrings on either side of all occurences of the \r\n within the CTBUFF instance value. Tokens are returned in a CTBUFFLST provided by the caller:
The CTBUFFLST instance must be provided by the caller meaning that the caller must create a CTBUFFLST instance via the CTBUFFLST_Constructor method and pass it as the @Tokens parameter to the CTBUFF_Split method.
Examples
Example
/include QINCSRC,CTBASE
DpBuffer S *
DpTokens S *
DpVarValues S *
DString S 255A
DBuffer S 255A
DSeparator S 10A
DSepSize S 10I 0
DBytes S 10I 0
DRc S 10I 0
Di S 10I 0
Dj S 10I 0
DCount S 10I 0
DCount_2 S 10I 0
DCrLf S 2A Inz(x'0D25')
/Free
pBuffer = CTBUFF_Constructor();
pTokens = CTBUFFLST_Constructor();
pVarValues = CTBUFFLST_Constructor();
String = 'Hello World';
CTBUFF_Set(pBuffer: %Addr(String): %Len(%Trim(String)));
// We want all tokens separated by a blank character
Separator = ' ';
SepSize = 1;
CTBUFF_Split(pBuffer: %Addr(Separator):
SepSize: pTokens);
// Let's look at the result ...
Count = CTBUFFLST_Count(pTokens);
For i=1 To Count By 1;
Bytes = %Size(Buffer);
Buffer = *Blanks;
CTBUFFLST_GetValue(pTokens: %Addr(Buffer): Bytes: i);
EndFor;
String = 'GET / HTTP 1.0' + CrLf;
String = %Trim(String) + 'content-type: text/html' + CrLf;
String = %Trim(String) + CrLf;
CTBUFF_Set(pBuffer: %Addr(String): %Len(%Trim(String)));
//////////////////////////////////////////////////////////
// Let's extract all lines...
// An HTTP request separates its data from its headers
// by an empty line. In the following example, we
// have two consecutive CRLF, which amounts to an empty
// line at the end of the string AND ALSO an empty line
// AFTER the last CRLF (so there are actually 4 lines).
// Notice that the last two tokens are returned with a
// size of zero (meaning that nothing was copied in the
// outbound buffer). However, it is considered a token
// (hence the CT_SUCCESS return value).
//////////////////////////////////////////////////////////
Separator = CrLf;
SepSize = 2;
CTBUFF_Split(pBuffer: %Addr(Separator):
SepSize: pTokens);
Count = CTBUFFLST_Count(pTokens);
For i=1 To Count By 1;
Bytes = %Size(Buffer);
Buffer = *Blanks;
Rc = CTBUFFLST_GetValue(pTokens: %Addr(Buffer): Bytes: i);
EndFor;
///////////////////////////////////////////////////////
// Rather than retrieve values in a supplied ALPHA
// field, we could retrieve the lines in a CTBUFF
// instance and parse the lines further with a call
// to CTBUFF_Split on the token itself ...
// This way, we can get all variable:value pairs
// of every HTTP header.
///////////////////////////////////////////////////////
For i=1 To Count By 1;
Rc = CTBUFFLST_GetBuffer(pTokens: pBuffer: i);
// We know that headers start after the first line ...
If i > 1;
If CTBUFF_Length(pBuffer) > 0; // not an empty line|
// Get header variable:value pair ...
// use another CTBUFFLST instance so
// we don't overwrite our lines by using pTokens
Separator = ':';
SepSize = 1;
CTBUFF_Split(pBuffer: %Addr(Separator):
1: pVarValues);
Count_2 = CTBUFFLST_Count(pVarValues);
For j=1 To Count_2 By 1;
Bytes = %Size(Buffer);
Buffer = *Blanks;
Rc = CTBUFFLST_GetValue(pVarValues:
%Addr(Buffer): Bytes: j);
EndFor;
EndIf;
EndIf;
EndFor;
CTBUFF_Destructor(pBuffer);
CTBUFFLST_Destructor(pTokens);
CTBUFFLST_Destructor(pVarValues);
*InLR = *On;
Return;
/End-Free