---
name: "DlpReadRecordByID"
section: "3"
platform: "linux"
package: "coldsync"
version: "3.0+pre3-3"
release: "Debian 4.0 (Etch)"
platforms: ["linux"]
url: "https://new.carta.tech/DlpReadRecordByID"
---

# DlpReadRecordByID(3)

read a record from a PalmOS device

## NAME

**DlpReadRecordByID**, **DlpReadNextModifiedRec**, **DlpReadRecordByIndex**, **DlpReadNextRecInCategory**, **DlpReadNextModifiedRecInCategory** – read a record from a PalmOS device

## LIBRARY

*libpconn*

## SYNOPSIS

**#include \<palm.h\>**

**#include \<pconn/pconn.h\>**

*int*\

**DlpReadRecordByID**(*PConnection \*pconn*, *const ubyte handle*, *const udword id*, *const uword offset*, *const uword len*, *struct dlp\_recinfo \*recinfo*, *const ubyte \*\*data*);

*int*\

**DlpReadRecordByIndex**(*PConnection \*pconn*, *const ubyte handle*, *const uword index*, *struct dlp\_recinfo \*recinfo*);

*int*\

**DlpReadNextModifiedRec**(*PConnection \*pconn*, *const ubyte handle*, *struct dlp\_recinfo \*recinfo*, *const ubyte \*\*data*);

*int*\

**DlpReadNextRecInCategory**(*PConnection \*pconn*, *const ubyte handle*, *const ubyte category*, *struct dlp\_recinfo \*recinfo*, *const ubyte \*\*data*);

*int*\

**DlpReadNextModifiedRecInCategory**(*PConnection \*pconn*, *const ubyte handle*, *const ubyte category*, *struct dlp\_recinfo \*recinfo*, *const ubyte \*\*data*);

## DESCRIPTION

These functions read a record from the Palm. In all of these functions, *pconn* is the Palm connection, as returned by [new\_PConnection(3)](/new_PConnection/3.md). *handle* is a database handle, as returned by [DlpOpenDB(3)](/DlpOpenDB/3.md).

If a record has been deleted and expunged (*i.e.*, when the record was deleted and the “Save archive copy on PC” checkbox was unchecked), the length of the record's data will be given as 0, and *data* will point to an empty string.

**DlpReadRecordByID** is the preferred way of reading a record from the Palm.

*id* specifies the identifier of the record to be retrieved; this identifier is usually gotten with **DlpReadRecordIDList**().

*offset* is the offset at which to begin reading the record: to read the record from the beginning, use 0; to skip the first 10 bytes, use 10.

*len* specifies the maximum number of bytes to read.

*recinfo* will be filled with the record header, which has the following form:

```
struct dlp_recinfo
{
	udword id;
	uword index;
	uword size;
	ubyte attributes;
	ubyte category;
};
```

*data* will be filled in with a pointer to the record data. This pointer is to an internal buffer, and must not be freed. The length of the data will be the smaller of *recinfo.size* and *len*.

**DlpReadRecordByIndex** is less useful than it might seem. It reads the header of the *indexth* record, but not the record data. Thus, if you only want to read the twelfth record in a database and nothing else, you can use **DlpReadRecordByIndex**() to get the index of the twelfth record, then use **DlpReadRecordByID**() to read the record's data.

*index* specifies the index of the record whose header to retrieve. Record indices begin at 0. *recinfo*, as with **DlpReadRecordByID**(), will be filled in with the record header.

**DlpReadNextModifiedRec** reads the next record in the database that has been modified since the last sync (or, more accurately, since the modification flags were reset by [DlpResetSyncFlags(3)](/DlpResetSyncFlags/3.md) ). Modified records include those whose contents have changed; those that have been moved to a different category; and those that have been deleted, with or without an archive copy.

*handle*, *recinfo*, and *data* are as for **DlpReadRecordByID**().

**DlpReadNextRecInCategory** reads the next record in the given category.

*category* specifies the index of the category, in the range 0-15, with 0 being reserved for the “Unused” category. The category ID can be gotten from the category list at the start of the AppInfo block. Sadly, although the category list is in a standard format, libpconn does not include a facility for parsing it.

*recinfo* and *data* are as for **DlpReadRecordByID**().

**DlpReadNextModifiedRecInCategory** reads the next modified record in the given category. All arguments are as for **DlpReadNextRecInCategory**().

## RETURN VALUE

All of these functions return 0 if successful, or a negative value otherwise.

## SEE ALSO

[libpconn(3)](/libpconn/3.md), [new\_PConnection(3)](/new_PConnection/3.md), [DlpOpenDB(3)](/DlpOpenDB/3.md), [DlpReadRecordIDList(3)](/DlpReadRecordIDList/3.md), [DlpResetRecordIndex(3)](/DlpResetRecordIndex/3.md).