Selective Replication

Chapter 9-7

Selective Replication

In Domino and Notes, you can restrict the amount of information exchanged between replicas. You can select documents to replicate by document type, according to a selection formula, or both. You can use selective replication to conserve disk space or reduce connection time on dial-up lines.

You can store replicas on a number of different servers. A server containing a database replica that will receive new or updated documents is called a destination server. A server containing a database replica from which documents are pulled is called a source server.

Domino and Notes stores selective replication information in a replication formula note, one replication formula note for each specified destination server. For a locally administered database, the local server is the only destination server, so there is only one replication formula note. For a centrally administered database, the manager of the master database may specify the replication criteria for replicas stored on a number of different servers. There would then be a replication formula note for each specified destination server.

NOTE: The selective replication note is valid only for the database in which it is stored; the formula only affects what gets pulled into the database whenever its server is the destination server during replication.


Components of a Replication Formula Note

A replication formula note is a note of class NOTE_CLASS_REPLFORMULA. It contains a $TITLE item, a $ReplVersion item, a $ReplSrcServers item, a $ReplClassMasks item, and one or more $ReplFormula items.


$TITLE

The $TITLE item is a text item that contains a string specifying the name of the destination server to which this note applies. This is usually the server on which the current instance of the database resides. If the replication formula note is in a database on a workstation and defines server-to-workstation replication, this item contains the workstation name.


$ReplVersion

The $ReplVersion item is a text item that contains the character '1' followed by a null terminator.


$ReplSrcServers

The $ReplSrcServers item is of type TYPE_TEXT_LIST. It contains a list of the names of servers from which notes will be replicated using the replication formula. If you want to use the default value ("- Any Server -"), enter a dash ("-") in the text list as shorthand.


$ReplClassMasks

The $ReplClassMasks item is a text list item that specifies the types of notes that will be replicated with each of the source servers. Each entry in the $ReplClassMasks list specifies the document types that will be pulled from the corresponding server in the $ReplSrcServers list.

The bitmasks in NOTECLASS define the types of notes that will be replicated. The string stored in the text list for each source server is a character representation of the decimal value of the bitmask. For example, if only Icon notes are to be replicated, the text string "16" is stored in the text list, since NOTE_CLASS_ICON is defined as 0x0010 (16 decimal).


$ReplFormula

The $ReplFormula item is of type TYPE_FORMULA and consists of a compiled selection formula. There is one $ReplFormula item for each member of the $ReplSrcServers list. Each $ReplFormula item specifies the selection formula used to replicate documents from the corresponding member of the server list.


$ReplView

The $ReplView item is of type TYPE_TEXT_LIST. It contains either an explicit list of shared folders and views to be replicated, or it is NULL, which means that all shared folders and views are to be replicated.


$ReplPrivateFolder

The $ReplPrivateFolder item is of type TYPE_TEXT_LIST. It contains either an explicit list of private folders and views to be replicated, or it is NULL, which means that all private folders and views are to be replicated.


$ReplFields

The $ReplFields item is of type TYPE_TEXT_LIST. It contains either an explicit list of field names to be replicated, or it is NULL, which means that all fields are to be replicated.


The SEL_REP Sample Program

The sample program SEL_REP opens a database located on a HCL Domino Server and creates a replica copy of it on the workstation. SEL_REP then creates a replication formula note in the local copy of the database. This replication note specifies that when receiving documents from replicas located on any server, only documents with a value less than 100 stored in the numberfield item will be pulled from the server replica. SEL_REP is in the directory samples\admin\sel_rep.

The program creates a new note in the database and sets the note class to NOTE_CLASS_REPLFORMULA.

SEL_REP: Adding the $TITLE and $ReplVersion items.

/
*  Set the name of the destination for replicated notes. ($TITLE item).
*  In this case, the destination is the local workstation.
*  First, get the name of the workstation's user.
/
    if (!OSGetEnvironmentString ("KeyFileName", IDFileSpec,
                                 MAXENVVALUE))

    {
       NSFDbClose(hDB);            / Close database            /
       API_RETURN (ERR(sError));
   }
   if (sError = REGGetIDInfo (IDFileSpec, REGIDGetName, UserName,
                              MAXUSERNAME+1, &retUserNameLen))
   {
       NSFDbClose(hDB);            / Close database            /
       API_RETURN (ERR(sError));
   }

/
*  Now set the $TITLE item.
/
   if (sError = NSFItemSetText(hNote,
                               REPLFORMULA_SERVER_ITEM,
                               UserName,
                               MAXWORD))
   {
       NSFDbClose(hDB);            / Close database            /
       API_RETURN (ERR(sError));
   }
/
*  Set the REPLFORMULA_VERSION_ITEM.
/
    if (sError = NSFItemSetText(hNote,
                               REPLFORMULA_VERSION_ITEM,
                               "1",
                               MAXWORD))
   {
       NSFDbClose(hDB);            / Close database            /
       API_RETURN (ERR(sError));
   }


The above code first sets the $TITLE item, which specifies the destination for replication. Since we are replicating from a server to the workstation, the destination is the user's name. The code calls SECKFMGetUserName to get the name of the user and adds this to the note as an item of TYPE_TEXT.

Next, the code adds the $ReplVersion item. This must be the text string "1".

SEL_REP: Adding the $ReplSrcServers item.

/
*  Create the $ReplSrcServers. This is a text list containing the
*  names of all source servers.

*  First, allocate a buffer in which the TEXT_LIST will be built.
/
    if (sError = OSMemAlloc (0, wTextBufferLength, &hMem))
       API_RETURN (FALSE);
/
*  Lock global buffer.
/
   if ((pBuffer = OSLockObject(hMem)) == NULL)
   {
       OSMemFree (hMem);
       API_RETURN (FALSE);
   }
/
*  Set start length to zero, and point the item pointer to the
*  start of the buffer.
/          
    wItemLength = 0;
   pItem = pBuffer;
/
*  Now fill in text list of server names containing database replicas that
*  documents could be pulled from.  In this example, there is only
*  one entry, the default "- Any Server -", represented by a single dash
*  ("-").  This is the required shorthand for specifying "- Any Server -".
*  This means that when replicating from any server, use the
*  information in this note.

*  If different replication criteria were desired for documents being pulled
*  from a specific server, that server's name would be added as another entry
*  in the text list.
/
   ((USHORT )pItem) = 1;       /  Set number of entries.  /
   pItem += sizeof(WORD);
   wItemLength += sizeof(WORD);
 /
   Set length of first source server.
 /
    ((WORD )pItem) = sizeof(SrcServerName)-1;
   pItem += sizeof(WORD);
   wItemLength += sizeof(WORD);
 /
   First source server name.
 /
   memcpy(pItem, SrcServerName, sizeof(SrcServerName) -1);
   pItem += (sizeof(SrcServerName) - 1);
   wItemLength += (sizeof(SrcServerName) - 1);
/
*  Append the $ReplSrcServers item to the note.
/
    if (sError = NSFItemAppend(hNote,
                              ITEM_SUMMARY,
                              REPLFORMULA_SOURCE_SERVERS,
                              sizeof (REPLFORMULA_SOURCE_SERVERS)-1,
                              TYPE_TEXT_LIST,
                              pBuffer,
                              wItemLength))
   {
       OSUnlockObject (hMem);
       OSMemFree (hMem);
       NSFDbClose(hDB);             / Close database            /
       API_RETURN (ERR(sError));
   }


The $ReplSrcServer item is a text list containing the names of the servers for which replication formulas are defined. In this example, the only entry in the list is "-" (short for "- Any Server -"). This means that the replication criteria specified in this note are to be used when pulling documents from a replica located on any server. If you want to associate different replication criteria with a specific server, add that server's name to the text list and add corresponding entries in the other items.

SEL_REP: Adding the $ReplClassMasks item

/
*  Create the $ReplClassMask item. There is only one entry in the text
*  list, since in this example the replication criteria are the same
*  regardless of which server the documents are being pulled from.  If
*  more than one server were specified in $ReplSrcServers item,
*  character strings representing the classes of documents to be replicated
*  from the corresponding servers would need to be added to the text list.
/
/
*  Reset start length to zero, and point the item pointer to the
*  start of the buffer.
/          
    wItemLength = 0;
   pItem = pBuffer;

    ((USHORT )pItem) = 1;              /  Set number of entries.  /
   pItem += sizeof(WORD);
   wItemLength += sizeof(WORD);
/
*  Convert the note class mask to a character string.
/
   iClasses = MY_NOTE_CLASSES;
   _itoa (iClasses, ClassMaskString, 10);
/
*  Set length of mask string.
 /
    ((WORD )pItem) = strlen(ClassMaskString);
   pItem += sizeof(WORD);
   wItemLength += sizeof(WORD);
 /
   Copy mask string.
 /
   memcpy(pItem, ClassMaskString, strlen(ClassMaskString));
   pItem += (strlen(ClassMaskString));
   wItemLength += (strlen(ClassMaskString));
/
*  Append the $ReplClassMasks item to the note.
/
    if (sError = NSFItemAppend(hNote,
                              ITEM_SUMMARY,
                              REPLFORMULA_NOTECLASS_ITEM,
                              sizeof (REPLFORMULA_NOTECLASS_ITEM)-1,
                              TYPE_TEXT_LIST,
                              pBuffer,
                              wItemLength))
   {
       OSUnlockObject (hMem);
       OSMemFree (hMem);
       NSFDbClose(hDB);             / Close database            */
       API_RETURN (ERR(sError));
   }

$ReplClassMasks is a text list that specifies the classes of documents that will be replicated when pulling documents from the corresponding servers listed in the $ReplSrcServers list. The bitfields in NOTE_CLASS denote the list of document classes. The entries in the $ReplClassMasks text list are character representations of the decimal values of the bitmasks.

This example replicates the same classes of documents with all servers. The bitmask specifying the server classes is defined in sel_rep.h. The code converts the mask to a character string and stores the string in the $ReplClassMask list for both entries.

SEL_REP: Adding the $ReplFormula item.

/
*  Create a $ReplFormula item.  If more than one entry was specified for
*  The $ReplSrcServers item, a $ReplFormula item would be needed for each
*  server, and the order of the $ReplFormula items appeared would correspond
*  to the order of server names in the text list.

*  Compile the selection formula, get a pointer to it,and append
*  it to the note.
/
    if (sError = NSFFormulaCompile(NULL,
                                  0,
                                  szSelFormula,
                                  strlen(szSelFormula),
                                  &hSelFormula,
                                  &wSelFormulaLen,
                                  &wdc, &wdc, &wdc,
                                  &wdc, &wdc))
   {
       OSUnlockObject (hMem);
       OSMemFree (hMem);
       NSFDbClose(hDB);             / Close database            /
       API_RETURN (ERR(sError));
   }

    pSelFormula1 = OSLockObject(hSelFormula);
/
*  Append the $ReplFormula item to the note.
/
    if (sError = NSFItemAppend(hNote,
                              ITEM_SUMMARY,
                              REPLFORMULA_FORMULA_ITEM,
                              sizeof (REPLFORMULA_FORMULA_ITEM)-1,
                              TYPE_FORMULA,
                              pSelFormula,
                              wSelFormulaLen))
   {
       OSUnlockObject (hMem);
       OSMemFree (hMem);
       NSFDbClose(hDB);             / Close database            /
       API_RETURN (ERR(sError));
   }
/
*  Unlock and free memory associated with this formula.
*/
    OSUnlockObject(hSelFormula);
   OSMemFree(hSelFormula);


A $ReplFormula item is of type TYPE_FORMULA. It defines the selection criteria for documents that will be replicated. There is one $ReplFormula item for each server with which the workstation will replicate, and they must appear in the same order as their corresponding entries in the $ReplSrcServer item.

In this sample, the formula stored in the $ReplFormula item is "Select (numberfield < 100)". This means that the program replicates only documents containing a value less than 100 in the field named "numberfield". All documents of the appropriate classes are replicated.

After the program creates the replication formula note, it updates the note, closes the database, and exits.

---