Reading a Record

Other versions of this page are also available for the following:

• Windows Embedded CE 6.0 R3

8/28/2008

Once a record is found, call the CeReadRecordPropsEx (CEDB) function to read the properties of the record, specifying an array of property identifiers. Also, specify the buffer to which to write property data and the size of the buffer. Setting the CEDB_ALLOWREALLOC flag in the dwFlags parameter reallocates the buffer if the returned data is too large. If the database is stored in a compressed format, the database engine must decompress records in 4-KB blocks as they are read.

CeReadRecordPropsEx can return selected record properties or a full view of all properties. You can allocate memory from the local heap to return the record values. CeReadRecordPropsEx can use any heap to return record values, not just the local heap. For efficiency, read all desired properties in a single call.

If you do check for a specific property, check for the CEDB_PROPNOTFOUND flag in the CEPROPVAL (CEDB) structure for that property. The record might not have the property that you are looking for.

When Windows Embedded CE reads a record property successfully, the system copies the property information into the specified buffer as an array of CEPROPVAL structures. The CeReadRecordPropsEx function returns the Windows Embedded CE object identifier of the record. All variable-size data, such as strings and binary large objects (BLOBs), is copied to the end of the buffer. The CEPROPVAL structures contain pointers to this data.

The following code example shows how to create and write the following properties:

• A 16-bit signed integer
• A 32-bit signed integer
• A null-terminated string
• A BLOB to the new record

void ReadingDBRecords (void)
{
   CEOID CeOid;           // Object identifier of the record read.
   PCEGUID pceguid;       // Pointer to the mounted database volume.
   WORD wcPropID;         // Number of properties retrieved.
   DWORD dwcbBuffer,      // Count of bytes of the *lpBuffer.
   dwError;               // Return value of the GetLastError function.
   TCHAR szMsg[100];      // String for displaying the error message.
   LPBYTE lpBuffer = NULL; // Pointer to a buffer that receives record property data.
   HANDLE hDataBase,      // Handle to a database to be opened.
   hHeap;                 // Handle to the heap for allocating records.
   CEGUID guid;           // Assign to pceguid the GUID of the mounted volume in which the database resides.
   // Create the heap by calling HeapCreate to allocate the database records.
   // Open the database with the current seek position to be incremented automatically with each call.
   hHeap = GetProcessHeap();
   pceguid= &guid;
   hDataBase = CeOpenDatabaseEx (
      pceguid,            // Pointer to the mounted volume.
      &CeOid,             // Location of the database identifier.
      TEXT("MyDBase"),    // Database name.
      0,                  // Sort order; 0 indicates to ignore.
      CEDB_AUTOINCREMENT, // Automatically increase seek pointer.
      NULL);              // Does not need to receive notification.
   // Check for errors on the hDataBase handle before continuing.
   if (hDataBase == INVALID_HANDLE_VALUE)
   {
      // Your error-handling code goes here.
      return;
   }
   while ((CeOid = CeReadRecordPropsEx (hDataBase, // Handle of the database.
      CEDB_ALLOWREALLOC,  // Use LocalAlloc to get the buffer.
      &wcPropID,          // Number of properties retrieved.
      NULL,               // NULL means retrieve all properties.
      &lpBuffer,          // Buffer receives property data.
      &dwcbBuffer,        // Count of bytes in *lpBuffer.
      hHeap)) != 0)       // Handle to the heap for allocating the record when CEDB_ALLOWREALLOC is specified.
      {
         // The record is now available in the lpBuffer. Add code here to manipulate the properties in this record.
      }
      // Error handling if CeReadRecordPropsEx fails
      dwError = GetLastError ();
      if (dwError == ERROR_NO_MORE_ITEMS)
      {
         wsprintf (szMsg, TEXT("Read through all records in the database."));
      }
      else if (dwError == ERROR_INSUFFICIENT_BUFFER)
      {
         wsprintf (szMsg, TEXT("Re-allocation of database records failed."));
      }
      else
      {
         wsprintf (szMsg, TEXT("Other errors."));
      }
      // Close the database handle.
      CloseHandle (hDataBase);
   }
}

See Also

Concepts

CEDB Database Support