_itemCopyC()
 Copy a character item's value into a C buffer
------------------------------------------------------------------------------
 C Prototype

     #include "item.api"
     USHORT _itemCopyC(
                        ITEM itmChar,
                        BYTEP fpBuffer,
                        USHORT uiSize
                      )

 Arguments

     itmChar is the item from which to get a character value.

     fpBuffer is the preallocated buffer to copy the item's value into.

     uiSize is fpBuffer's size (one-based).  If this parameter is zero,
     _itemCopyC() will assume that the buffer is of adequate size to hold the
     string.

 Returns

     The number of characters copied into the character buffer.

 Description

     The _itemCopyC() function copies an item's character value into a buffer
     of uiSize length.  This is useful when you need to be in control of
     allocation and deallocation of the buffer used for the item's value.

     Warning!  You are responsible for allocating and freeing a buffer of
     adequate size for the item.  There is no need to call _itemFreeC()
     when using _itemCopyC() as with _itemGetC().

 Examples

     /*
     *
     * CharCount( cString, cChar )
     *
     * Count occurrences of a single character
     * in a CA-Clipper string.  Version 1.00
     *
     */

     CLIPPER CharCount( void )
     {
        USHORT uiChars = 0;
        USHORT uiLen;
        USHORT i;
        HANDLE vmhString;

        BYTEP  cStringP;
        BYTE   cFindMe;

        ITEM   itmString, itmFindMe, itmRet;

        if (PCOUNT != 2)
        {
           _ret();               // NOTE: Withhold service
           return;               // Early return!
        }

        itmRet    = _itemPutNL( NULL, 0 );
        itmString = _itemParam( 1 );
        itmFindMe = _itemParam( 2 );

        if ( (_itemType( itmString ) == CHARACTER) &&
              (_itemType( itmFindMe ) == CHARACTER) )
        {
           _itemCopyC( itmFindMe, &cFindMe, 1 );

           vmhString = _xvalloc( _itemSize( itmString ), NULL );
           cStringP = _xvlock( vmhString );

           uiLen = _itemCopyC( itmString, cStringP, NULL );

           for( i = 0; i < uiLen; i++ )
           {
              if ( cStringP[i] == cFindMe )
                 uiChars++;
           }

           _xvunlock( vmhString );
           _xvfree( vmhString );

           itmRet = _itemPutNL( itmRet, (long)uiChars );

        }

        _itemReturn( itmRet );

        _itemRelease( itmRet );
        _itemRelease( itmString );
        _itemRelease( itmFindMe );

        return;
     }

 Files  Library is CLIPPER.LIB, header file is Item.api.