Writing Documents

Chapter 5-4

Writing Documents

Writing a Domino or Notes document consists of two steps:

1. Opening or creating the document
2. Writing fields into the document

The first part of this chapter explains how to open an existing document or create a new document. The second part shows how to write fields of four basic data types: plain text, numbers, time/date, and text lists.

We will use the sample program WSIMPLE (short for WriteSIMPLE) to explain writing documents. WSIMPLE is in the subdirectory samples\basic\wsimple. Load wsimple.c in an editor or print it so you can refer to it while you read this chapter.


Opening and Creating Documents

Documents are notes of class NOTE_CLASS_DOCUMENT. The procedures for opening, creating, updating, and closing documents are the same for all classes of notes.

You must open a note before you can write or modify data in the note. The function NSFNoteOpen opens a note in a database. NSFNoteOpen requires a NOTEID as input to specify the note, so the note must already exist. The "Reading Documents" chapter shows how to find a note and get the NOTEID using the function NSFSearch. NSFNoteOpen yields a note handle, which is required for most reads and all writes to the fields.

Use NSFNoteCreate to create a new note. NSFNoteCreate also opens the new note, returning a note handle.


Updating and Closing Documents

Creating or opening a note causes Domino or Notes to maintain an object in memory specified by the note handle. The note handle is required for most reads and all writes to the fields. Any write to a field of a note is held in memory until the note is updated to disk. The function NSFNoteUpdate takes a note handle as input and updates the .nsf file on disk with all the fields written using that handle. Data written using the note handle must be updated to disk before the note is closed, otherwise the data is discarded. Use NSFNoteClose to close any open note and release the memory when the handle is no longer needed.

The segment of wsimple.c below creates a new note in preparation for writing fields to the document, updates the note to the database on disk, and closes the note.

wsimple.c: Creating and Updating a Note

  DBHANDLE   db_handle;   / database handle      /
 NOTEHANDLE note_handle; / note handle        /
 STATUS     error;       / return code from API calls /

  if (error = NSFNoteCreate (db_handle, &note_handle))
 {
     PrintAPIError(error);
      NSFDbClose (db_handle);
      NotesTerm();
      return(1);
 }
 .
 . Add and modify fields in the document.
 .

  / Add the new note to the database. /
 if (error = NSFNoteUpdate (note_handle, 0))
 {
      PrintAPIError(error);
     NSFNoteClose (note_handle);
     NSFDbClose (db_handle);
     NotesTerm();
      return(1);
 }

  / Close the note. (Remove its structure from memory.) /
 if (error = NSFNoteClose (note_handle))
 {
      PrintAPIError(error);
     NSFDbClose (db_handle);
     NotesTerm();
      return(1);
 }


Writing Fields

WSIMPLE calls NSFNoteCreate to create a new note before writing fields in it. NSFNoteCreate yields a note handle. WSIMPLE needs this handle when it calls C API functions such as NSFItemSetText to write data to the fields in the document.

A document can contain any number of fields. Each field has a Field Name, a Data Type, a Data Length, a Data Value, and a flag word. Domino and Notes support many different data types. WSIMPLE demonstrates writing fields of four basic data types: text, number, time/date, and text list.

The API provides specific functions, such as NSFItemSetText, to write fields of each of the four basic data types. The API also provides general functions, such as NSFItemAppend, to write any field of any data type. All functions that write fields require as input the note handle, the name of the field, and the data to write. The format of the data depends on the data type.

WSIMPLE writes five fields to the new document. The first two fields are named FORM and PLAIN_TEXT, respectively, and are both of type text. The third field is named NUMBER and is of type number. The fourth field is named TIME_DATE and is of type time/date. The last field is named TEXT_LIST and is of type text list.


Writing the FORM Field

When creating new documents, a field named FORM is often written to the document to specify a default form to use to display this document. The FORM field should be of type text. Its value should be identical to the name of a form in the database, as specified in the Properties for Form Infobox in the Notes user interface.

wsimple.c: Writing the FORM Field

  NOTEHANDLE note_handle;  / note handle         /
 STATUS     error;        / return code from API calls /

  / Write the FORM field to the note -- this field specifies
  the default form to use when displaying the note./

  if (error = NSFItemSetText ( note_handle,
       "FORM",
       "SimpleDataForm",
       MAXWORD))
 {
      PrintAPIError(error);
     NSFNoteClose (note_handle);
     NSFDbClose (db_handle);
     NotesTerm();
      return(1);
 }


Writing Text Fields

WSIMPLE uses NSFItemSetText to write data to a text field named PLAIN_TEXT. WSIMPLE uses the string "The quick brown fox jumped over the lazy dogs." for the data value.

wsimple.c: Writing a Text Field

  DBHANDLE  db_handle;   / database handle       /
 NOTEHANDLE note_handle;  / note handle         /
 STATUS   error;     / return code from API calls /

  / Write a text field named PLAIN_TEXT to the note. /

  if (error = NSFItemSetText ( note_handle,
       "PLAIN_TEXT",
       "The quick brown fox jumped over the lazy dogs.",
       MAXWORD))
 {
      PrintAPIError(error);
     NSFNoteClose (note_handle);
     NSFDbClose (db_handle);
     NotesTerm();
      return(1);
 }

This call to NSFItemSetText writes a new text field called PLAIN_TEXT. The actual text is the third argument. The fourth argument specifies the length of the text.

If the fourth argument is specified as MAXWORD, the string must be a null-terminated string, and NSFItemSetText will write all the characters up to the first NULL character. Specifying the length of the string explicitly, instead of specifying MAXWORD, lets you write a string of text containing embedded NULL characters to the document.


Writing Number Fields

WSIMPLE uses the API function NSFItemSetNumber to write a field named NUMBER, of data type TYPE_NUMBER, to the document.

wsimple.c: Writing a Number to a Document

  NOTEHANDLE note_handle; / note handle         /
 NUMBER     num_field;   / contents of a numeric field /
 STATUS     error;       / return code from API calls /

/ Write a field named NUMBER to the note. /

  num_field = 125.007;

  if (error = NSFItemSetNumber (note_handle, "NUMBER", &num_field))
 {
      PrintAPIError(error);
     NSFNoteClose (note_handle);
     NSFDbClose (db_handle);
     NotesTerm();
      return(1);
 }

WSIMPLE initializes the variable num_field to the value 125.007. The variable num_field is of type NUMBER, which is defined by the HCL C API for Domino and Notes to be an eight-byte double. NSFItemSetNumber requires as input a pointer to a variable of this type.


Writing Time/Date Fields

WSIMPLE use the API function NSFItemSetTime to write a time/date field named TIME_DATE to the new document. The time/date value it writes is the current time/date, obtained by calling the API function OSCurrentTIMEDATE.

wsimple.c: Writing a Time/Date Field to a Document

NOTEHANDLE   note_handle;  / note handle /
TIMEDATE     timedate;     / contents of a time/date field /
STATUS       error;        / return code from API calls /

  / Get the current time/date and write it
    to a field named TIME_DATE. /

OSCurrentTIMEDATE(&timedate);

if (error = NSFItemSetTime (note_handle, "TIME_DATE", &timedate))
     {
          PrintAPIError(error);
   NSFNoteClose (note_handle);
   NSFDbClose (db_handle);
    NotesTerm();
          return(1);
}

WSIMPLE calls OSCurrentTIMEDATE to initialize the variable timedate to the current time and date. The variable timedate is of type TIMEDATE. The HCL C API for Domino and Notes defines the type TIMEDATE. NSFItemSetTime requires a pointer to a variable of type TIMEDATE to set the value.


Writing Text-List Fields

Text-list fields are multi-valued text fields. WSIMPLE uses a three step process to write a text-list field named TEXT_LIST with three values to the new document. The three text values are the strings "Charles," "Janet," and "Chuck."

To create a text-list field, use NSFItemCreateTextList, which also puts the first value in the field. Then use NSFItemAppendTextList to add additional values to the field.

wsimple.c: Writing a Text-List Field to a Document

  NOTEHANDLE note_handle;  / note handle         /
 STATUS     error;        / return code from API calls /

  / Create a text-list field and add it to the note. /
 if (error = NSFItemCreateTextList ( note_handle,
       "TEXT_LIST",
       "Charles",
       MAXWORD))
 {
      PrintAPIError(error);
     NSFNoteClose (note_handle);
     NSFDbClose (db_handle);
  NotesTerm();
      return(1);
 }

  / Add an item to the text-list field. /
 if (error = NSFItemAppendTextList ( note_handle,
       "TEXT_LIST",
       "Janet",
       MAXWORD,
       TRUE))
 {
      PrintAPIError(error);
     NSFNoteClose (note_handle);
     NSFDbClose (db_handle);
     NotesTerm();
      return(1);
 }
  / Add another item to the text-list field. /
  if (error = NSFItemAppendTextList ( note_handle,
  "TEXT_LIST",
  "Chuck",
  MAXWORD,
  TRUE))
 {
      PrintAPIError(error);
NSFNoteClose (note_handle);
     NSFDbClose (db_handle);
      NotesTerm();
      return(1);
 }

In this example, NSFItemCreateTextList creates the text-list field TEXT_LIST with the initial entry "Charles." Then NSFItemAppendTextList adds the string "Janet" to the same field. At this point there are two entries in the field TEXT_LIST. The second call to NSFItemAppendTextList appends the third value, "Chuck," to the text list.

After writing these fields to the document, WSIMPLE updates the note as explained above, closes the note, closes the database, and returns.

Special Field - Do Not Create a Replication or Save Conflict
If a note has a $ConflictAction field with a value of "2" in it, the Replicator will NOT create a replication conflict document. If you do not want a note to replicate, create an item of TYPE_TEXT and name it $ConflictAction. Set its value to "2".

---