RXSTRINGs

Many of the Rexx application programming interfaces pass Rexx character strings to and from a Rexx procedure. The RXSTRING data structure is used to describe Rexx character strings. An RXSTRING is a content-insensitive, flat model character string with a theoretical maximum length of 4 gigabytes. The following structure defines an RXSTRING:

typedef struct {
   ULONG           strlength;     /* length of string             */
   PCH             strptr;        /* pointer to string            */
} RXSTRING;

typedef RXSTRING *PRXSTRING;      /* pointer to an RXSTRING       */

Notes:

1. The Rexx.H include file contains a number of convenient macros for setting and testing RXSTRING values.

2. An RXSTRING can have a value (including the null string, "") or it can be empty.

   • If an RXSTRING has a value, the strptr field is not null. The RXSTRING macro RXVALIDSTRING(string) returns TRUE.

   • If an RXSTRING is the Rexx null string (""), the strptr field is not null and the strlength field is 0. The RXSTRING macro RXZEROLENSTRING(string) returns TRUE.

   • If an RXSTRING is empty, the field strptr is null. The RXSTRING macro RXNULLSTRING(string) returns TRUE.

3. When the Rexx interpreter passes an RXSTRING to a subcommand handler, external function, or exit handler, the interpreter adds a null character (hexadecimal zero) at the end of the RXSTRING data. You can use the C string library functions on these strings. However, the RXSTRING data can also contain null characters. There is no guarantee that the first null character encountered in an RXSTRING marks the end of the string. You use the C string functions only when you do not expect null characters in the RXSTRINGs, such as file names passed to external functions. The strlength field in the RXSTRING does not include the terminating null character.

4. On calls to subcommand and external functions handlers, as well as to some of the exit handlers, the Rexx interpreter expects that an RXSTRING value is returned. The Rexx interpreter provides a default RXSTRING with a strlength of 256 for the returned information. If the returned data is shorter than 256 characters, the handler can copy the data into the default RXSTRING and set the strlength field to the length returned.

   If the returned data is longer than 256 characters, a new RXSTRING can be allocated using GlobalAlloc(size). The strptr field must point to the new storage and the strlength must be set to the string length. The Rexx interpreter returns the newly allocated storage to the system for the handler routine.