_itemRelease()
 Make an item available for garbage collection
------------------------------------------------------------------------------
 C Prototype

     #include "item.api"
     BOOL _itemRelease(
                        ITEM itmRef
                      )

 Arguments

     itmRef is the item to release.

 Returns

     TRUE if the item passed was successfully released.

 Description

     The _itemRelease() function drops your Extend routine's reference to a
     CA-Clipper-level item.  If your Extend routine was the only reference to
     that item, then the item becomes garbage and a candidate for collection.
     However, if the item is referred to elsewhere, then it will not be
     collected until its last reference is released.

     Warning!  It is vitally important that items be released once you no
     longer have need for them.  Failure to do so may cause a CA-Clipper
     stack fault or memory errors.

 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.