Issue a read notes request to read the collection of notes defined by the specified selection criteria. An answer area must be provided. A buffer area is optional. XCF scans the note pad, inspecting each note to see if it satisfies the selection criteria. Metadata for each of the selected notes is stored in the answer area. The note metadata includes the note tag, instance number, connection identifier, persistence attribute, and note size. If a suitable buffer area is provided, the content of each selected note is stored in the buffer area. If a note has content (not a null note), the metadata in the answer area for that note will also indicate the location of the note content within the buffer area. A valid read request returns to the caller when all the notes have been inspected, or when the storage areas provided for output are filled with as many notes as will fit, whichever comes first.

For a read notes request, your program might need to repeatedly issue the request to fetch all of the selected notes. Such situations occur when the data for the selected notes will not fit in the output storage areas provided by your program (answer area and buffer area). When the read request completes prematurely in this fashion, your program must reissue the request to continue reading the remaining notes. A resume token is used to maintain the context so that each iteration (reissue) of the read request continues on from where the prior read left off. The number of times that the request needs to be reissued to finish reading the notes will in general decrease as the size of the provided storage areas increases. The duration of each such request will likely increase since more notes can be processed on each call. You might choose to issue a query note pad request to determine the number of notes in the note pad to estimate how much storage would be needed to read all the notes.

Figure 1. Multi-note answer area with buffer

Note: All offsets are relative to the start of the answer area.

Take note of the discussion of Concurrent request issues. In particular, the read notes request scans the notes in created timestamp order. If your program concurrently creates notes while the read notes request is being processed, the timing of the interplay between these requests could be such that the read notes request might fail to read a note that satisfies the selection criteria. Your program might need to account for this possibility.