8.1.4.1 The RXSTRING structure

The SAA API interface uses Rexx string which are stored in the
structure RXSTRING. There is also a datatype PRXSTRING, which is a
pointer to RXSTRING. Their definitions are:

     typedef struct {
           unsigned char *strptr ;    /* Pointer to string
     contents */
           unsigned long strlength ;  /* Length of string */
     } RXSTRING ;

     typedef RXSTRING *PRXSTRING ;

The strptr field is a pointer to an array of characters making up
the contents of the Rexx string', while strlength holds the number
of characters in that array.

Unfortunately, there are some inconsistencies in naming of various
special kinds of strings. In REXX (TRL), a ``null string'' is a
string that has zero length. On the other hand, the SAA API
operates with two kinds of special strings: null strings and zero
length strings. The latter is a string with zero length (equals
null strings in REXX), while the former is a sort of  undefined or
empty string, which denotes a string without a value. The null
strings of SAA API are used to denote unspecified values (e.g. a
parameter left out in a subroutine call). In this chapter, when
the terms null strings and zero length strings are italicized,
they refer to the SAA API style meaning.

A number of macros are defined, which simplifies operations on
RXSTRINGs for the programmer. In the list below, all parameters
called x are of type RXSTRING.

·    MAKERXSTRING(x,content,length)]
     The parameter content must be a pointer to char, while length
     is integer. The x parameter will be set to the contents and
     length supplied. The only operations are assignments;  no new
     space is allocated and the contents of the string is not
     copied.
·    RXNULLSTRING(x)]
     Returns true only if x is a null string.
     i.e.  x.strptr is NULL.
·    RXSTRLEN(x)]
     Returns the length of the string x as an unsigned long. Zero
     is returned both when x is a null string or a zero  length
     string.
·    RXSTRPTR(x)]
     Returns a pointer to the first character in the string x, or
     NULL if x is a null string. If x is a zero length string, and
     non-NULL pointer is returned.
·    RXVALIDSTRING(x)]
     Returns true only if x is neither a null string nor a  zero
     length string
     i.e. x must have non-empty contents.
·    RXZEROLENSTRING(x)]
     Returns true only if x is a zero length string.
     i.e.  x.strptr is non-NULL, and  x.strlength is  zero.

These definitions are most likely to be defined as preprocessor
macros, so you should never call  them with parameters  having any
side effects. Also note that at least MAKERXSTRING() is likely to
be implemented as two statements, and might not work properly if
following
e.g. an if statement. Check the actual definitions in the
rexxsaa.h header file before using them in a fancy context.

One definition of these might be (don't rely on this to be the
case with your implementation):

      #define MAKERXSTRING(x,c,l)
     ((x).strptr=(c),(x).strlength=(l))
      #define RXNULLSTRING(x)     (!(x).strptr)
      #define RXSTRLEN(x)         ((x).strptr ? (x).strlength :
     0UL)
      #define RXSTRPTR(x)         ((x).strptr)
      #define RXVALIDSTRING(x)    ((x).strptr && (x).strlength)
      #define RXZEROLENSTRING(x)  ((x).strptr && !(x).strlength)

Note that these definitions of strings differ from the normal
definition in C programs; where a string is an array of
characters, and its length is implicitly given by a terminating
ASCII NUL character. In the  RXSTRING definition, a string can
contain any character, including an ASCII NUL, and the length is
explicitly given.

 PREV   NEXT