Click above to get retro games delivered to your door ever month!

 _itemPutCL()
 Place a character value into an Item, ignoring null-terminators
------------------------------------------------------------------------------
 C Prototype

     #include "item.api"
     ITEM _itemPutCL(
                      ITEM itemChar,
                      BYTEP fpChars,
                      USHORT uiLen
                    )

 Arguments

     itemChar is the item into which you want to place the string.  If
     itemChar is NULL, _itemPutCL() will create a new Item.

     fpChars is the zero-terminated string to place into the Item.

     uiLen is the number of bytes to place into the Item.

 Returns

     A new Item reference containing the string passed.

 Description

     The _itemPutCL() function is used to associate any string with an Item,
     ignoring embedded nulls.  Any previous value in itemChar will be
     destroyed.

     The data located at fpChars is copied into a new space associated with
     the Item that is returned.  It is the programmer's responsibility to
     free the allocation of fpChars in whatever manner it was allocated.

     Note:  _itemPutCL() must copy the intended string from your buffer
     at fpChars.  If fpChars is unusually large, _itemPutCL() may cause a VM
     failure due to insufficient real memory to accomplish a large copy.
     Typically, this error would manifest itself as an internal error 5302.

     Caution!  Do not assume that the address in itemChar will be the
     same address returned by _itemPutCL().

 Examples

     /*
     *
     * BootSector( [nDrive] ) -> cBootSecBuff
     *
     * Read the boot sector from drive nDrive,
     * if there is no drive specified, BootSector()
     * reads drive A.
     *
     * (0=A, 1=B, 2=C, etc...)
     *
     * Warning: Does not check for errors.
     *          Needs dos.h & LLIBCA
     */

     CLIPPER BootSector( void )
     {
        ITEM   itemDriveN, itemBuff;
        BYTEP  bufferP;
        HANDLE vmBuffer;
        USHORT uiDriveN = 0;            // Default: A
        USHORT uiLen = 1024;

        union  REGS  preCallRx, postCallRx;
        struct SREGS theSegs;

        if ( PCOUNT > 0 )
        {
           itemDriveN = _itemParam( 1 );

           if ( _itemType( itemDriveN ) | NUMERIC )
              uiDriveN = (USHORT) _itemGetNL( itemDriveN );

           _itemRelease( itemDriveN );
        }

        vmBuffer = _xvalloc( uiLen );
        bufferP  = _xvlock( vmBuffer );

        segread( &theSegs );

        theSegs.es     = FP_SEG( bufferP );
        preCallRx.x.bx = FP_OFF( bufferP );
        preCallRx.x.ax = 0x0201;            // BIOS 02 / 1 sector
        preCallRx.x.cx = 1;                 // Track 0, Sector 1
        preCallRx.x.dx = uiDriveN;          // Side 0, Drive uiDriveN

        int86x( 0x13, &preCallRx, &postCallRx, &theSegs );

        if ( postCallRx.x.cflag )
           ERRMSG( "\r\nERROR on read!" );

        itemBuff = _itemPutCL( NULL, bufferP, uiLen );

        _xvunlock( vmBuffer );
        _xvfree( vmBuffer );

        _itemRelease( _itemReturn( itemBuff ) );

        return;
     }

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