String handling

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.

Warning: The internal structure of a CPSTR is reserved and should not be accessed directly. Failure to abide by this rule will definitely guarantee incompatibility with future releases.

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.