Clara-Doc - Method Reference
CTBUFF_Set
Description
Initialises the CTBUFF instance value from a supplied buffer. A CTBUFF instance can hold any type of value such as character strings, sound files, images, etc. When passing a character string, make sure you pass the actual size in bytes. Some character representations use more than one byte for some characters (such as UTF-8 and unicode). Since a CTBUFF instance works with binary data, the character string size in bytes, not in characters, must be provided.
Prototype
DCTBUFF_Set...
D PR 10I 0
D@This * Value
D@Str * Value
D@Len 10I 0 Value
Parameters
@This
| Type | Pointer (*) |
| Passing Mode | Value |
| Description | The address of an CTBUFF instance. This pointer MUST be obtained through a call to CTBUFF_Constructor. |
@Str
| Type | Pointer (*) |
| Passing Mode | Value |
| Description | The address of a byte buffer that will be copied to the CTBUFF value. The byte buffer will replace the current CTBUFF value. |
@Len
| Type | 10I 0 |
| Passing Mode | Value |
| Description | The length in bytes of the byte buffer used to set the CTBUFF value. Remember that this is the length in bytes of the buffer. If the buffer holds a character string, don't specify the string length (because in some cases such as UTF-8, the string length could be lower than the actual buffer size because some characters may be coded by more than one byte). |
Return Values
Returns the length in bytes of the new CTBUFF instance value. Remember to distinguish between a character string (which could hold characters coded by more than one byte) and a byte string. The return value is the byte string length, not the character string length when a character string is used.
Examples
/include QINCSRC,CTBASE
DpBuffer S *
DpIndices S *
DString S 255A
DPattern S 10A
DIndex S 10I 0
DPatSize S 10I 0
DBytes S 10I 0
DRc S 10I 0
Di S 10I 0
DCount S 10I 0
/Free
pBuffer = CTBUFF_Constructor();
String = '12345678ABCDEFGHIJKLMNOP';
CTBUFF_Set(pBuffer: %Addr(String): %Len(%Trim(String)));
// We want to get the string ABC (3 characters from position 9).
// Remember that positions are one-based, meaning that the first
// byte is at position 1
Bytes = 3;
CTBUFF_Get(pBuffer: %Addr(String): 9: Bytes);
// Oops! the string is ABC4567890ABCDEFGHIJKLMNOP
// That's because the buffer is a byte buffer, not an ALPHA
// field! We need to initialise the target before before
// calling CTBUFF_Get.
String = *Blanks;
Bytes = 3;
CTBUFF_Get(pBuffer: %Addr(String): 9: Bytes);
// You can extract the whole string by specifying
// a byte size of -1. On return, the actual size
// of the value will be held in the Bytes parameter:
String = *Blanks;
Bytes = -1;
CTBUFF_Get(pBuffer: %Addr(String): 1: Bytes);
// You can extract from one position up to the end with
// a byte size of -1: The actual size copied will be held
// in the Bytes parameter on return:
String = *Blanks;
Bytes = -1;
CTBUFF_Get(pBuffer: %Addr(String): 9: Bytes);
CTBUFF_Destructor(pBuffer);
*InLR = *On;
Return;
/End-Free
> EVAL String
STRING =
....5...10...15...20...25...30...35...40...45...50...55...60
1 'ABC45678ABCDEFGHIJKLMNOP '
61 ' '
121 ' '
181 ' '
241 ' '
> EVAL String
STRING =
....5...10...15...20...25...30...35...40...45...50...55...60
1 'ABC '
61 ' '
121 ' '
181 ' '
....5...10...15...20...25...30...35...40...45...50...55...60
1 '12345678ABCDEFGHIJKLMNOP '
61 ' '
121 ' '
181 ' '
241 ' '
> EVAL String
STRING =
....5...10...15...20...25...30...35...40...45...50...55...60
1 'ABCDEFGHIJKLMNOP '
61 ' '
121 ' '
181 ' '
241 ' '
241 ' '