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:
RXSTRING data structure

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

Notes:

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

• 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 non-NULL. The RXSTRING macro RXVALIDSTRING(string) returns TRUE.

  • If an RXSTRING is the REXX null string (""), the strptr field is non-NULL and the strlength field is zero. 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 may also contain null characters. There is no guarantee that the first null character encountered in an RXSTRING marks the end of the string. 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 some of the exit handlers, the REXX interpreter expects an RXSTRING value 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 DosAllocMem. The strptr field must point to the new storage and the strlength must be set to the string length. The REXX interpreter will return the newly allocated storage to the system for the handler routine.

  ---

  [Back: Handler Characteristics]
  [Next: Calling the REXX Interpreter]