home *** CD-ROM | disk | FTP | other *** search
/ The Developer Connection…ice Driver Kit for OS/2 3 / DEV3-D1.ISO / devtools / os2tk21j / rexx / samples / rxstring / rxstring.do_ / rxstring.doc
Encoding:
Text File  |  1993-03-12  |  4.1 KB  |  97 lines
  1.               RXSTRING.LIB - Library of functions for RXSTRING's
  2.  
  3.  
  4.  
  5. The RXSTRING.LIB library provides analogues of many of the standard C library
  6. functions for the RXSTRING structure (which is used in conjunction with the
  7. REXX interpreter), as well as a sampling of functions which convert standard
  8. C strings into RXSTRING's.
  9.  
  10. The functions provided for OS/2 2.0 are 32-bit only.  They must be called
  11. from 32-bit code.  For 16-bit RXSTRING functions, use the 1.2 or 1.3 OS/2 Toolkit
  12. version of RXSTRING.LIB
  13.  
  14. The following functions are available:
  15.  
  16.    Group 1: Numeric conversion functions
  17.  
  18.       INT   rxtoi(RXSTRING);
  19.       LONG  rxtol(RXSTRING);
  20.       ULONG rxtoul(RXSTRING);
  21.  
  22.       - these functions convert RXSTRING's into integer values, similar to the
  23.         atoi(), atol(), and atoul() functions
  24.  
  25.    Group 2: File I/O functions
  26.  
  27.       LONG rxwrite(HFILE, RXSTRING);
  28.       LONG rxread(HFILE, PRXSTRING);
  29.       VOID rxprint(RXSTRING)
  30.  
  31.       - these functions will read and write RXSTRING's, including structure
  32.         information, to and from a file, as well as writing the data contained
  33.         in an RXSTRING to stdout
  34.  
  35.    Group 3: Copy / Conversion functions
  36.  
  37.       RXSTRING rxstrdup(RXSTRING);
  38.       RXSTRING rxmemcpy(PRXSTRING, PRXSTRING, ULONG);
  39.       RXSTRING rxstrcpy(PRXSTRING, PRXSTRING); 
  40.       RXSTRING rxstrncpy(PRXSTRING, PRXSTRING, ULONG); 
  41.       RXSTRING rxstrcat(PRXSTRING, PRXSTRING);        
  42.       RXSTRING rxstrncat(PRXSTRING, PRXSTRING, ULONG); 
  43.       RXSTRING strdup2rx(PUCHAR, ULONG);
  44.       RXSTRING memcpy2rx(PRXSTRING, PUCHAR, ULONG);
  45.       RXSTRING strcpy2rx(PRXSTRING, PSZ);
  46.       RXSTRING strcat2rx(PRXSTRING, PSZ);
  47.       RXSTRING strncat2rx(PRXSTRING, PSZ, ULONG);
  48.  
  49.       - these functions will duplicate, copy and/or concatenate RXSTRING's with
  50.         RXSTRING's and RXSTRING's with standard strings/buffers
  51.  
  52.         NOTE: Except for the "dup" functions, all of the functions require that
  53.               the destination string contain sufficient storage for completion
  54.               of the requested operation.  The concatenation functions begin
  55.               appending at the current length of the RXSTRING.  Therefore,
  56.               enough storage should be available for the original length plus
  57.               the length of the data to be added to the string.
  58.  
  59.    Group 4: Comparison / Character functions
  60.  
  61.       LONG  rxstrcmp(PRXSTRING, PRXSTRING);        
  62.       LONG  rxstricmp(PRXSTRING, PRXSTRING);        
  63.       LONG  rxmemcmp(PRXSTRING, PRXSTRING, ULONG); 
  64.       LONG  rxmemicmp(PRXSTRING, PRXSTRING, ULONG); 
  65.       PUCHAR rxstrchr(PRXSTRING, UCHAR);
  66.       PUCHAR rxstrrchr(PRXSTRING, UCHAR);            
  67.  
  68.       - these functions are analogues of the standard C library comparison
  69.         functions (strcmp, stricmp, memcmp, and memicmp) and character
  70.         search functions (strchr and strrchr), and return values similar to
  71.         those functions
  72.  
  73.    Group 5: Miscellaneous functions
  74.  
  75.       RXSTRING rxalloc(ULONG);
  76.       VOID rxfree(RXSTRING);
  77.       VOID rxstrnset(RXSTRING, UCHAR, ULONG);
  78.       ULONG rxstrlen(RXSTRING);
  79.       RXSTRING rxset_length(PRXSTRING, ULONG);
  80.       RXSTRING rxset_null(PRXSTRING);
  81.       RXSTRING rxset_zerolen(PRXSTRING);
  82.       RXSTRING rxreturn_value(PRXSTRING, PUCHAR, ULONG);
  83.       PUCHAR _make_hptr(RXSTRING);
  84.  
  85.       - the first three functions handle allocating, freeing, and overwriting
  86.         RXSTRING structures.  The rxstrlen and rxset_length functions retrieve
  87.         and set the length information contained in RXSTRING's without
  88.         affecting the associated memory for the string. The rxset_null function
  89.         sets the rxstring to null, similarly rxset_zerolen function sets the
  90.         rxstring to a zero length rxstring. The _make_hptr function returns a
  91.         pointer to the data buffer associated with an RXSTRING, if any
  92.         exists. The rxreturn_value function may be used to replace the logic
  93.         for figuring out if you should use the preallocated buffer for
  94.         return values or create your own buffer. The preallocated rxstring
  95.         return value is used with subcommands, external functions, and
  96.         variable pool.
  97.