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.

NOTE

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.