RXSTRING Library of Functions

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

The RXSTRING.LIB library provides analogues of many of the standard C library functions for the RXSTRING structure (which is used in conjunction with the REXX interpreter), as well as a sampling of functions which convert standard C strings into RXSTRING's.

The functions provided for OS/2 2.0 are 32-bit only. They must be called from 32-bit code. For 16-bit RXSTRING functions, use the 1.2 or 1.3 OS/2 Toolkit version of RXSTRING.LIB.

The following functions are available:

Group 1: Numeric conversion functions

INT   rxtoi(RXSTRING);
LONG  rxtol(RXSTRING);
ULONG rxtoul(RXSTRING);

• these functions convert RXSTRING's into integer values, similar to the atoi(), atol(), and atoul() functions

Group 2: File I/O functions

LONG rxwrite(HFILE, RXSTRING);
LONG rxread(HFILE, PRXSTRING);
VOID rxprint(RXSTRING)

• these functions will read and write RXSTRING's, including structure information, to and from a file, as well as writing the data contained in an RXSTRING to stdout

Group 3: Copy / Conversion functions

RXSTRING rxstrdup(RXSTRING);
RXSTRING rxmemcpy(PRXSTRING, PRXSTRING, ULONG);
RXSTRING rxstrcpy(PRXSTRING, PRXSTRING);
RXSTRING rxstrncpy(PRXSTRING, PRXSTRING, ULONG);
RXSTRING rxstrcat(PRXSTRING, PRXSTRING);
RXSTRING rxstrncat(PRXSTRING, PRXSTRING, ULONG);
RXSTRING strdup2rx(PUCHAR, ULONG);
RXSTRING memcpy2rx(PRXSTRING, PUCHAR, ULONG);
RXSTRING strcpy2rx(PRXSTRING, PSZ);
RXSTRING strcat2rx(PRXSTRING, PSZ);
RXSTRING strncat2rx(PRXSTRING, PSZ, ULONG);

• these functions will duplicate, copy and/or concatenate RXSTRING's with RXSTRING's and RXSTRING's with standard strings/buffers

NOTE: Except for the "dup" functions, all of the functions require that the destination string contain sufficient storage for completion of the requested operation. The concatenation functions begin appending at the current length of the RXSTRING. Therefore, enough storage should be available for the original length plus the length of the data to be added to the string.

Group 4: Comparison / Character functions

LONG  rxstrcmp(PRXSTRING, PRXSTRING);
LONG  rxstricmp(PRXSTRING, PRXSTRING);
LONG  rxmemcmp(PRXSTRING, PRXSTRING, ULONG);
LONG  rxmemicmp(PRXSTRING, PRXSTRING, ULONG);
PUCHAR rxstrchr(PRXSTRING, UCHAR);
PUCHAR rxstrrchr(PRXSTRING, UCHAR);

• these functions are analogues of the standard C library comparison functions (strcmp, stricmp, memcmp, and memicmp) and character search functions (strchr and strrchr), and return values similar to those functions

Group 5: Miscellaneous functions

RXSTRING rxalloc(ULONG);
VOID rxfree(RXSTRING);
VOID rxstrnset(RXSTRING, UCHAR, ULONG);
ULONG rxstrlen(RXSTRING);
RXSTRING rxset_length(PRXSTRING, ULONG);
RXSTRING rxset_null(PRXSTRING);
RXSTRING rxset_zerolen(PRXSTRING);
RXSTRING rxreturn_value(PRXSTRING, PUCHAR, ULONG);
PUCHAR _make_hptr(RXSTRING);

• the first three functions handle allocating, freeing, and overwriting RXSTRING structures. The rxstrlen and rxset_length functions retrieve and set the length information contained in RXSTRING's without affecting the associated memory for the string. The rxset_null function sets the rxstring to null, similarly rxset_zerolen function sets the rxstring to a zero length rxstring. The _make_hptr function returns a pointer to the data buffer associated with an RXSTRING, if any exists. The rxreturn_value function may be used to replace the logic for figuring out if you should use the preallocated buffer for return values or create your own buffer. The preallocated rxstring return value is used with subcommands, external functions, and variable pool.

IBM DISCLAIMS ALL WARRANTIES, WHETHER EXPRESSED OR IMPLIED, INCLUDING WITHOUT LIMITATION, WARRANTIES OF FITNESS AND MERCHANTABILITY WITH RESPECT TO THE INFORMATION IN THIS DOCUMENT. BY FURNISHING THIS DOCUMENT, IBM GRANTS NO LICENSES TO ANY RELATED PATENTS OR COPYRIGHTS.

Copyright IBM Corporation, 1992,1996. All Rights Reserved.