The standard C string type is not sufficient for handling the dynamic nature of D3 strings, so a hybrid data type has been created called CPSTR. This data type provides allocation, deallocation, and resizing of strings at a much higher performance level than that obtained using malloc() and free() with C strings.
The structure of a CPSTR is:
| Header | Internal use only-do not modify. |
| String | Character array containing the actual string. |
| Terminator | A single character used for termination. |
| Footer | Internal use only-do not modify. |
The macros listed below are provided to access all desired portions of a CPSTR structure:
| Macro | Description |
|---|---|
| _CP_SLEN(s) | Returns the current length of a string. This length does not include any terminating character such as a segment mark or a null character. |
| _CP_SADDR(s) | Returns a (char *) to the actual string
data that may or may not be terminated by a 0x00. Note that this (char *) must not be passed to the free() C function or to any C function that may try to use free() on the (char *). Allocation of CPSTR strings is accomplished via special allocation routines. CPSTR strings must not be allocated with the C function malloc(). The allocation routines provided set necessary internal flags, and are much more efficient than malloc(). Note: These routines create dynamic structures which must be deallocated
with the routines listed below.
|
| _CP_str_alloc(l) | Returns a CPSTR of length l. The actual string data portion of the string is undefined. |
| _CP_mkstr(char *s) | Returns a CPSTR from a C string s terminated by a null character. The string portion of the CPSTR will contain a copy of the C string's data. This function is less efficient than _CP_mkstrl as it must scan the C string to determine its length. |
| _CP_mkstrl(char *s, int l) | Returns a CPSTR from a C string s, of length l. The string portion of the CPSTR will contain a copy of the C string's data. |
| _CP_str_realloc(CPSTR **s, int l) | Resizes the CPSTR s. |
| _CP_str_free(CPSTR ** s) | Frees the desired string s. |
When the _CP_logoff call is executed, all CPSTRs remain valid, but they cannot be passed to any of the _CP_ routines. All CPSTRs are properly cleaned up when the C program exits.
It is necessary to free strings only when the user has finished with them completely. All resizing of strings is accomplished automatically by the _CP_ routines. For example, if a process repeatedly reads data into a buffer via the _CP_read call, this buffer will be automatically resized to fit the new data within the _CP_read call at every read.
The user must be careful with termination. Any _CP_ routine may modify the termination character. Therefore, the user must use the _CP_TERM() macro to terminate CPSTRs with a 0x00 if it is necessary to pass the string portion of it to a standard UNIX routine.