Function _conRLockC() Foundation

Locks a string container for direct read access.

Syntax
XPPAPIRET _conRLockC(ContainerHandle chs, CHAR **ppstr,
                     ULONG *pulSize);
Parameters
ContainerHandle chs
Handle of a container of character string type.
CHAR **ppstr
Buffer for the returned pointer to the character string. The string is not copied, but Fppstr points to the internal representation of the string. The pointer may be used for reading only. It is not allowed to change the string!
ULONG *pulSize
Pointer to a ULONG. After the call, this contains length of the string F*ppstr points to. Note:In Xbase++ character strings may contain NULL characters.
Return

The function returns an error code (XPP_ERR_...) when the container chs is not a character string or if the read access failed (e.g. if there is already a write-lock on the container). If the return value is NULL, the operation was successful.

Description

This function is used to read the value of a string container without copying the string into a buffer. However, the returned string pointer may never be used to change the string. There may be several containers which share the same internal string representation. After the value was read, the lock has to be removed with _conUnlock(). This should be done as soon as possible, because the garbage collector may be blocked otherwise.

Please note, that a NULL character is guaranteed after the end of the string but the string itself may contain NULL characters too.

If the container locked with _conRLockC() is a reference container returned from _conParam(), the unlock has to be done before one of the return functions (_ret...() or _conReturn()) is called! This restriction is valid only for reference containers and not for other parameter containers or locally created containers.

Examples
Retrieve the number of occurances of one string within another
#include <ctype.h>        /* toupper() */ 
#include "xpppar.h" 
#include "xppcon.h" 
/* 
FT_NOOCCUR( <cSuchDies>, <cHierDrin> 
            [, <lIgnoriereCase> ] )     -> <nAnzahl> 
*/ 
XPPRET XPPENTRY FT_NOOCCUR( XppParamList paramList ) 
{ 
ContainerHandle  chSearchFor; 
BOOL             sfRef; 
CHAR            *psf; 
ULONG            sfLen; 
ContainerHandle  chSearchIn; 
BOOL             siRef; 
CHAR            *psi; 
ULONG            siLen; 
BOOL             ignoreCase; 
ULONG            count = 0; 
ULONG            i; 

/* 
   Get the parameters (the 3rd parameter is optional and 
   as the default is FALSE we just use the _parl() function) 
*/ 
chSearchFor = _conParam( paramList, 1, &sfRef ); 
chSearchIn = _conParam( paramList, 2, &siRef ); 
ignoreCase = _parl( paramList, 3 ); 
#define CHRNEQ(a,b) (ignoreCase ? toupper(a) != toupper(b) : (a) != (b)) 

/* 
   lock both string parameters for read access 
*/ 
if (chSearchFor != NULLCONTAINER 
    &&  chSearchIn != NULLCONTAINER 
    &&  ! _conRLockC( chSearchFor, &psf, &sfLen )) 
{ 
   if (sfLen != 0  &&  ! _conRLockC( chSearchIn, &psi, &siLen )) 
   { 
      /* 
         search psf within psi 
      */ 
      while (siLen >= sfLen) 
      { 
         if (CHRNEQ(*psf, *psi)) 
         { 
            psi++; 
            siLen--; 
         } 
         else 
         { 
            for( i=1; i<sfLen; i++ ) 
               if (CHRNEQ(psf[i], psi[i])) 
                  break; 
            if (i != sfLen) 
            { 
               psi++; 
               siLen--; 
            } 
            else 
            { 
               count++; 
               psi += sfLen; 
               siLen -= sfLen; 
            } 
         } 
      } 
      /* 
         unlock read access of parameters 
      */ 
      _conUnlockC( chSearchIn ); 
   } 
   _conUnlockC( chSearchFor ); 
} 
/* 
   release parameter containers (if neccessary) 
   and set return value 
*/ 
if (chSearchFor != NULLCONTAINER && !sfRef) 
   _conRelease(chSearchFor); 
if (chSearchIn != NULLCONTAINER && !siRef) 
   _conRelease(chSearchIn); 

_retnl( paramList, count ); 
} 
Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.