Domino on Linux/Unix, Troubleshooting, Best Practices, Tips and more ...


Daniel Nashed

Updated: C-API - NIFReadEntries with SIGNAL_MORE_TO_DO in combination with NIFFindByName

Daniel Nashed – 6 August 2020 05:35:08

Yesterday I have been debugging an application issue in my sync tool. It was a very strange behavior which finally lead me to the following.

This is only interesting for my C-API development friends in the community and if you use NIFReadEntries for more than 16351 entries you should check your application.

The examples in the C-API toolkit shows the normal navigation without searching.
The Tumbler is set to 0 and NAVIATE_NEXT with a skip value of 1 is used.
But that doesn't work the same way with NIFFindByName().
The comment from Markus for this post pointed me to the difference. And this makes it even more confusing, but explains what is going on.

So I am updating this blog post. The example in the documentation is right. But it works differently when you use NIFFindByName().

If you start without a search operation and set the following, you are actually before the first element and need skip to the first entry:

 CollPos.Level = 0;

 CollPos.Tumbler[0] = 0;

For a find operation you are at a distinct current position where you want to get a current entry found.

So in that case you need a different way to navigate thru the collection.

By the way if you start at this position without a skip no documents are returned!

Here is what will not work if you used "find" and want the documents at the current position:

a.) Skip 1 for all including the first loop --> this will let you miss the first entry

b.) Skip 0 for all entries -> this will result in duplicate processing of the last element from the previous round --> happened in my case

The right way looks like the example appended. It will handle the first entry correctly and have no duplicate processing for the last entry in a round.

In my case double processing of the last element was problematic.

The following section in the doc explains what is happening:

" After a call to NIFReadEntries(), the collection position (parameter 2) points to the last entry read. You can use repeated calls to NIFReadEntries to move incrementally through a collection.  However, upon repeating the call to NIFReadEntries(), use one of the NAVIGATE_NEXT_xxx skip navigate flags (the third parameter) and use a skip count of 1L (the fourth parameter) to advance the collection position past the last one read so that it begins reading with the next entry in the collection.  "

If you use this function in a similar way in your code you should double check.

The point I did not take into account was reading without searching. My issue was after NIFFindByName()

There are examples in the SDK showing the correct way as well.
That shows that the examples are an important part of the SDK documentation ..

-- Daniel

Example code with the important parts highlighted

 error = NIFFindByName(

   hCollection,            /* collection to look in */

   "key",                  /* string to match on */

   FIND_CASE_INSENSITIVE,  /* match rules */

   &CollPos,               /* where match begins (return) */

   &dwMatchSize);          /* how many match (return) */

   AddInLogMessageText("%s: Entries matched :%u", 0, gTaskName, dwMatchSize);

bFirstLoop = TRUE;

do {

  error = NIFReadEntries(

    hCollection,               /* handle to this collection */

    &CollPos,                  /* where to start in collection */

    (WORD)(NAVIGATE_NEXT),     /* order to use when skipping */

    bFirstLoop ? 0L : 1L,      /* number to skip */

    NAVIGATE_NEXT,             /* order to use when reading */

    0xFFFFFFFF,                /* max number to read */

    READ_MASK_NOTEID,          /* info we want */

    &hBuffer,                  /* handle to info (return)   */

    NULL,                      /* length of buffer (return) */

    NULL,                      /* entries skipped (return) */

    &dwNotesFound,             /* entries read (return) */

    &wSignalFlag);             /* signal and share warnings (return) */

  bFirstLoop = FALSE;



    • [HCL Domino]
    • [Domino on Linux]
    • [Nash!Com]
    • [Daniel Nashed]