In Theory...

"Programming Domino With Java" - Final Flush

Bob Balaban — Mon, 2 Jan 2012 04:56:33 -0400

Happy New Year, Geeks!

Here's the 7th (and final) installment of the book. Thanks again for all the positive feedback.
The first installment can be found here
The 2nd installment is here
The 3rd is here
The 4th is here
The 5th is here
and the 6th is here

All of the book content (as is all of the content on this blog) is Copyright 1998 and 2011 by Looseleaf Software, Inc. You may not reproduce or distribute the book's content without permission from me.

Some Caveats and explanations:
- This book is now 12 years old. There are lots of things in it that are amusingly dated, even laughable. One example: the absurd emphasis on Java Applets. They died an unlamented death due to bloating a long time ago, but at the time I wrote the book, they were a hot technology.
- The formatting is not exactly as it first appeared in the book, and some of it is downright awkward. Sorry! The publisher converted the original files to Word for me, perhaps they forgot to select the "high-def" option.
- The Java package described in the book (lotus.notes) was superseded by lotus.domino in R5 (1999? I think). The methods are all mostly the same. Of course, IBM have added lots more classes and methods than existed when the book was written. Also, the "recycle()" method had not yet been invented in Domino 4.6, so the memory issues that call addresses are not really covered.
- The figures (screen shots and so on) referred to did not make it into any file format I can deal with, so I had to leave them out. Sorry! The code samples are mostly there, and I'll also post all of the files that were on the CD that came with the original book.

This Installment
This hunk is a zip file containing the contents of the CD that was included with the original book.
Appendix F (previously posted) contains a description of the contents of the CD: Appendix F.pdf

I have not gone back and checked that the samples still work. If you find that any do not, please let me know.
The JavaDoc, of course, corresponds to the Notes v4.0 release. "NOI" has come a long way since then, and the whole lotus.notes package was pretty much obsoleted in Notes v5, but they may still be distributing it.

CD.zip

Enjoy! Geek ya later

(Need expert application development architecture/coding help? Want me to help you invent directory services based on RDBMS? Need some Cloud-fu or some web services? Contact me at: bbalaban, gmail.com)
Follow me on Twitter @LooseleafLLC
This article �Copyright 2010 by Looseleaf Software LLC, all rights reserved. You may link to this page, but may not copy without prior approval.

"Programming Domino With Java" - Sixth Sip

Bob Balaban — Tue, 6 Dec 2011 12:17:56 -0400

Greetings, Geeks!

Here's the 6th installment of the book. Thanks again for all the positive feedback.
The first installment can be found here
The 2nd installment is here
The 3rd is here
The 4th is here
The 5th is here

All of the book content (as is all of the content on this blog) is Copyright 1998 and 2011 by Looseleaf Software, Inc. You may not reproduce or distribute the book's content without permission from me.

Some Caveats and explanations:
- This book is now 12 years old. There are lots of things in it that are amusingly dated, even laughable. One example: the absurd emphasis on Java Applets. They died an unlamented death due to bloating a long time ago, but at the time I wrote the book, they were a hot technology.
- The formatting is not exactly as it first appeared in the book, and some of it is downright awkward. Sorry! The publisher converted the original files to Word for me, perhaps they forgot to select the "high-def" option.
- The Java package described in the book (lotus.notes) was superseded by lotus.domino in R5 (1999? I think). The methods are all mostly the same. Of course, IBM have added lots more classes and methods than existed when the book was written. Also, the "recycle()" method had not yet been invented in Domino 4.6, so the memory issues that call addresses are not really covered.
- The figures (screen shots and so on) referred to did not make it into any file format I can deal with, so I had to leave them out. Sorry! The code samples are mostly there, and I'll also post all of the files that were on the CD that came with the original book.

This Installment

We're done with the main body of text (Chapters 1-14), but there's still more good stuff to post:

Appendix A "Useful Links and References" Appendix A.pdf

Appendix B "Notes Object Interface Class Diagram" (yeah, a little out of date now...)
Appendix B.pdf

Appendix C "Domino Setup For Writing Java Programs" Appendix C.pdf

Appendix D "Notes Object Interface Exceptions" Appendix D.pdf

Appendix E "Creating LSXs" (Note: This was WAY before Lotus released the "LSX Toolkit", known far and wide in song and legend. You can probably still get the toolkit at this site, though I haven't checked lately. It hasn't had a new release in years, and is known to be broken for recent versions of Microsoft Visual Studio)
Appendix E.pdf

Appendix F "What's On the CD-ROM" Appendix F.pdf

Next installment, I'll post the samples and javadoc from the CD

Enjoy! Geek ya later

"Programming Domino With Java" - Fifth Slug

Bob Balaban — Mon, 28 Nov 2011 18:22:21 -0400

Greetings, Geeks!

Here's the 5th installment of the book. Thanks again for all the positive feedback.
The first installment can be found here
The 2nd installment is here
The 3rd is here
The 4th is here

All of the book content (as is all of the content on this blog) is Copyright 1998 and 2011 by Looseleaf Software, Inc. You may not reproduce or distribute the book's content without permission from me.

Some Caveats and explanations:
- This book is now 12 years old. There are lots of things in it that are amusingly dated, even laughable. One example: the absurd emphasis on Java Applets. They died an unlamented death due to bloating a long time ago, but at the time I wrote the book, they were a hot technology.
- The formatting is not exactly as it first appeared in the book, and some of it is downright awkward. Sorry! The publisher converted the original files to Word for me, perhaps they forgot to select the "high-def" option.
- The Java package described in the book (lotus.notes) was superseded by lotus.domino in R5 (1999? I think). The methods are all mostly the same. Of course, IBM have added lots more classes and methods than existed when the book was written. Also, the "recycle()" method had not yet been invented in Domino 4.6, so the memory issues that call addresses are not really covered.
- The figures (screen shots and so on) referred to did not make it into any file format I can deal with, so I had to leave them out. Sorry! The code samples are mostly there, and I'll also post all of the files that were on the CD that came with the original book.

This Installment

This time I'm posting 3 more chapters:

Chapter 12: "NOI and Java Beans" (Are they really good for your heart?)
Chapter 12.pdf

Chapter 13: "JDBC and NOI"
Chapter 13.pdf

Chapter 14: A Look Ahead to Domino 5 (This ought to provide some laughs, eh?)
Chapter 14.pdf

Note: Chapter 14 is the last real chapter, but there's still plenty more to come. To wit:
- Appendices A through F
- Samples, including some javadoc, since I happen to have it anyway

Release Notes

Chapter 12: No bugs!
Chapter 13: No bugs!
Chapter 14: Also bug-free!

Enjoy! More soon. Geek ya later

"Programming Domino With Java" - Fourth Hit

Bob Balaban — Sun, 20 Nov 2011 14:30:47 -0400

Greetings, Geeks!

Here's the 4th installment of the book. Thanks again for all the positive feedback.
The first installment can be found here
The 2nd installment is here
The 3rd is here

All of the book content (as is all of the content on this blog) is Copyright 1998 and 2011 by Looseleaf Software, Inc. You may not reproduce or distribute the book's content without permission from me.

Some Caveats and explanations:
- This book is now 12 years old. There are lots of things in it that are amusingly dated, even laughable. One example: the absurd emphasis on Java Applets. They died an unlamented death due to bloating a long time ago, but at the time I wrote the book, they were a hot technology.
- The formatting is not exactly as it first appeared in the book, and some of it is downright awkward. Sorry! The publisher converted the original files to Word for me, perhaps they forgot to select the "high-def" option.
- The Java package described in the book (lotus.notes) was superseded by lotus.domino in R5 (1999? I think). The methods are all mostly the same. Of course, IBM have added lots more classes and methods than existed when the book was written. Also, the "recycle()" method had not yet been invented in Domino 4.6, so the memory issues that call addresses are not really covered.
- The figures (screen shots and so on) referred to did not make it into any file format I can deal with, so I had to leave them out. Sorry! The code samples are mostly there, and I'll also post all of the files that were on the CD that came with the original book.

This Installment

This time I'm posting 3 more chapters:

Chapter 9 (Debugging NOI Agents) - Chapter 09.pdf
NOTE: When I wrote the book, Eclipse was not yet invented (or at least, widely known). I hadn't yet come up with the now-common "2-Headed Beast" technique of debugging Java agents (Why hasn't IBM created a way to debug agents inside Designer in the 14 years that Java agents have been loose in the world? I don't know, but it's sad). See here for a description of "2-Headed Beast".

Chapter 10 (Sharing Objects Across Threads) - Chapter 10.pdf

Chapter 11 (Upgrading Servlets to Agents) - Chapter 11.pdf

Release Notes

Chapter 9: No bugs!

Chapter 10: No bugs!

Chapter 11: No bugs!

Enjoy! More soon. Geek ya later

"Programming Domino With Java" - Third Gulp

Bob Balaban — Mon, 14 Nov 2011 19:28:59 -0400

Greetings, Geeks!

Here's the third installment of the book. Thanks again for all the positive feedback.
The first installment can be found here
The 2nd installment is here

All of the book content (as is all of the content on this blog) is Copyright 1998 and 2011 by Looseleaf Software, Inc. You may not reproduce or distribute the book's content without permission from me.

Some Caveats and explanations:
- This book is now 12 years old. There are lots of things in it that are amusingly dated, even laughable. One example: the absurd emphasis on Java Applets. They died an unlamented death due to bloating a long time ago, but at the time I wrote the book, they were a hot technology.
- The formatting is not exactly as it first appeared in the book, and some of it is downright awkward. Sorry! The publisher converted the original files to Word for me, perhaps they forgot to select the "high-def" option.
- The Java package described in the book (lotus.notes) was superseded by lotus.domino in R5 (1999? I think). The methods are all mostly the same. Of course, IBM have added lots more classes and methods than existed when the book was written. Also, the "recycle()" method had not yet been invented in Domino 4.6, so the memory issues that call addresses are not really covered.
- The figures (screen shots and so on) referred to did not make it into any file format I can deal with, so I had to leave them out. Sorry! The code samples are mostly there, and I'll also post all of the files that were on the CD that came with the original book.

This Installment

I'm including 3 chapters in this post:

Chapter 6 (NOI Part 5): Chapter 06.pdf

Chapter 7 (Writing NOI Applications): Chapter 07.pdf

Chapter 8 (Writing NOI Agents): Chapter 08.pdf

Release Notes

Chapter 6, Page 195. Description of Registration.addUserProfile() mistakenly refers to Database.createProfileDocument(). Should be setProfileDocument()

Chapter 7, no bugs!

Chapter 8, Page 265. Listing 8.3 ("Waiting for Child Threads, Ex83Multi.java). Sigh. This code has a major race condition in it that I didn't catch until after the book was out. Basically, the problem is that all of the threads could finish before you get to the logic that tests to see if any of them are alive. There's a better and much more robust pattern for doing this stuff that I could write a separate article about, if there's interest.

Enjoy! More soon. Geek ya later

"Programming Domino With Java": Chunk the Second

Bob Balaban — Wed, 9 Nov 2011 17:28:19 -0400

Greetings, Geeks!

Here's the second installment of the book. Thanks again for all the positive feedback.
The first installment can be found here

All of the book content (as is all of the content on this blog) is Copyright 1998 and 2011 by Looseleaf Software, Inc. You may not reproduce or distribute the book's content without permission from me.

Some Caveats and explanations:
- This book is now 12 years old. There are lots of things in it that are amusingly dated, even laughable. One example: the absurd emphasis on Java Applets. They died an unlamented death due to bloating a long time ago, but at the time I wrote the book, they were a hot technology.
- The formatting is not exactly as it first appeared in the book, and some of it is downright awkward. Sorry! The publisher converted the original files to Word for me, perhaps they forgot to select the "high-def" option.
- The Java package described in the book (lotus.notes) was superseded by lotus.domino in R5 (1999? I think). The methods are all mostly the same. Of course, IBM have added lots more classes and methods than existed when the book was written. Also, the "recycle()" method had not yet been invented in Domino 4.6, so the memory issues that call addresses are not really covered.
- The figures (screen shots and so on) referred to did not make it into any file format I can deal with, so I had to leave them out. Sorry! The code samples are mostly there, and I'll also post all of the files that were on the CD that came with the original book.

This Installment

I'm including 3 chapters in this post:

Chapter 3 (NOI Part 2) -- was supposed to be in the previous posting, but ooops. Sorry: Chapter 03.pdf

Chapter 4 (NOI Part 3): Chapter 04.pdf

Chapter 5 ( Yes! You guessed it...NOI Part 4): Chapter 05.pdf

Don't worry, the chapter titles get a little more inventive starting with Chapter 7.

Release Notes

Chapter 3:
Page 98, All of the "Item.appendXXX" method names should have capitalized "Value"

Page 113, discussion of "auto-update", it describes how you can use getNextDocument(), etc. "That'll work okay". It won't work ok, it'll potentially cause an infinite loop. Ooops.

Page 117, Listing 3.6, the "for" loop starts an index at 0, should be 1. Same for the loop on Page 118 as well.

Page 119, mentions a property on View named "IsHierarchical". There is no such property (or at least, there wasn't in 4.6)

Chapter 4:
No bugs!

Chapter 5:
No bugs!

Enjoy! More soon. Geek ya later

"Programming Domino With Java" - First Installment

Bob Balaban — Wed, 2 Nov 2011 19:50:15 -0400

Greetings, Geeks!

Here's the first installment of the book. Thanks again for all the positive feedback.

All of the book content (as is all of the content on this blog) is Copyright 1998 and 2011 by Looseleaf Software, Inc. You may not reproduce or distribute the book's content without permission from me.

Some Caveats and explanations:
- This book is now 12 years old. There are lots of things in it that are amusingly dated, even laughable. One example: the absurd emphasis on Java Applets. They died an unlamented death due to bloating a long time ago, but at the time I wrote the book, they were a hot technology.
- The formatting is not exactly as it first appeared in the book, and some of it is downright awkward. Sorry! The publisher converted the original files to Word for me, perhaps they forgot to select the "high-def" option.
- The Java package described in the book (lotus.notes) was superseded by lotus.domino in R5 (1999? I think). The methods are all mostly the same. Of course, IBM have added lots more classes and methods than existed when the book was written. Also, the "recycle()" method had not yet been invented in Domino 4.6, so the memory issues that call addresses are not really covered.
- The figures (screen shots and so on) referred to did not make it into any file format I can deal with, so I had to leave them out. Sorry! The code samples are mostly there, and I'll also post all of the files that were on the CD that came with the original book.

This Installment
I'm including the Dedication/Preface, and Chapters 1 ("Programmability Overview"), 2 ("NOI Part 1") and 3 ("NOI Part 2"). "NOI" is "Notes Object Interface", what we called the "back-end classes" in the day.

Preface/etc.: ded_ack_pref.pdf

Chapter 1: Chapter 01.pdf

Chapter 2: Chapter 02.pdf

Release Notes

Chapter 2:
Page 15, "Refer to Appendix A for a diagram...", should be "Appendix B"

Page 33, Listing 2.2, Missing closing curly-brace "}" right before the "catch" statement

Page 58, description of Database.createCopy() method, should mention that the method does not copy data, only the design of the db

Chapter 3:
Page 98, All of the "Item.appendXXX" method names should have capitalized "Value"

Page 113, discussion of "auto-update", it describes how you can use getNextDocument(), etc. "That'll work okay". It won't work ok, it'll potentially cause an infinite loop. Ooops.

Page 117, Listing 3.6, the "for" loop starts an index at 0, should be 1. Same for the loop on Page 118 as well.

Page 119, mentions a property on View named "IsHierarchical". There is no such property (or at least, there wasn't in 4.6)

Enjoy! More soon.

Anyone interested in me posting my 1998 book?

Bob Balaban — Sat, 29 Oct 2011 10:34:15 -0400

Greetings, Geeks!

In 1998 I published a book titled "Programming Domino 4.6 With Java" (see the Amazon page here). It did fairly well, but of course it's a bit dated now, and it went out of print in 2000.

While you can apparently get a used copy for $0.59 (plus shipping), I was thinking I might post the PDF version of the whole thing here on my blog (the rights to the book reverted to me when the publisher declared it out of print, so it's legal). There are bugs in there, which I suppose I could publish "release notes" for, too. I think it's still the best detailed description of the Java "back-end classes" for N/D, as that library existed in October, 1997.

Any interest? If you'd like to see it, post a comment here. If you wouldn't like to see it, post a comment here.

Geek ya later!

Check out CouchConf in New York, October 24

Bob Balaban — Mon, 10 Oct 2011 18:59:10 -0400

CouchDb has gained notice in recent years as an innovator in the "NoSQL" data management space. CouchDb was invented by Damien Katz (http://damienkatz.net/), a former colleague of mine from the old days at Iris Associates. Couch is now open-sourced (via Apache, I think) and Damien's new company, CouchBase (http://www.couchbase.com/), helps organizations use it effectively to solve all sorts of business (and other) problems.
If you're in the New York City area on October 24th, check it out.

Geek-O-Terica 16: Easy conversion of Notes documents to MIME format (Part 2)

Bob Balaban — Mon, 4 Apr 2011 06:45:00 -0400

Greetings, Geeks!

Recently I posted some sample code showing you how to convert Notes documents to MIME format on disk, using the Notes Java APIs. Unfortunately, if you need to do this kind of conversion using some other platform (such as .net), the job is a bit harder. A key method on the Document class (doc.convertToMIME()) is missing in the COM classes for Notes. Why? No idea, someone should ask Lotus about that. Probably has something to do with fear (but that's just speculation on my part).

No worries, though. the convertToMIME() method uses public C API calls to do its work, so we can do the same from a .net program. For starters, see my blog post on calling C API from C# (c-sharp) programs, here. That post talks about the basic techniques and syntax for setting up any kind of call-out from C# to C, so I won't repeat that here (the idea is just about the same if you're using vb). Here's a c-sharp file that provides a bunch of wrappers for Notes C API calls, bundled together in a class called NotesEntriess. NotesEntries.cs

The tedious bit about doing MIME conversion for a .net program is that there are several C calls you have to make for the 1 Java/LotusScript call. The tricky part is that, to do it without having to do everything at the C API level, you want to save typing by leveraging the COM classes, and only use the NotesEntries wrappers when you have to. The problem is that the COM classes do not expose the in-memory "handle" for a NotesDocument instance -- you can only get the Note ID -- while the C API calls require the handle for most things.

So you'll see in the sample program "BlogMIME.cs" (BlogMIME.cs) that the first part of the work (converting a document to MIME format in memory) is done with C API wrappers (after using "regular" COM classes to access the NSF and find the document in the first place, of course). I could have continued to use the C API to iterate over MIMEParts in the converted document, force Base64 encoding, and write out the results, but it's really much easier to do all that using COM classes. Unfortunately, there's no way to take the NOTEHANDLE that I get using the C API and use it to get a NotesDocument COM object. I had to save() the document back to disk, get the Note ID, and use that to "get" the document again via COM. There's a slight performance hit for the extra save, but it was worth it in this case.

You'll notice that the c# code that actually writes out the converted MIME document to disk is almost a line-for-line translation of the Java code I posted earlier. That's possible because the Notes COM classes are almost identical (on purpose) to the Java and LotusScript interfaces. The only reason we have to get tricky with using C API wrappers is that the Document.convertToMIME() function is missing in the COM interface.

There are some other nice (reusable) features of the c# code, such as mapping various C constants to c# syntax, and so on. So, take the code, use it as a source of techniques for doing this kind of integration. Enjoy!

Geek ya later.

Geek-O-Terica 15: Easy conversion of Notes documents to MIME format (Part 1)

Bob Balaban — Mon, 21 Mar 2011 06:00:00 -0400

Greetings, Geeks!

MIME is a data format that has become central to transmission of email over the Internet. The nice thing about it is that everyone uses it for mail interchange, and that it's standard. The Domino server converts incoming MIME-formatted messages into Notes documents, and outgoing Notes email documents into MIME formats. As of (I think) Notes v6, you can specify that you want incoming MIME messages to remain in their native format within the NSF database. In these cases, the Notes client will automatically convert any document that resides in MIME format to "regular" Notes rich text document format when you open it in the client UI.

What does MIME format look like? It can get complicated, but the easiest way to think of it is as a sectioned box, with each compartment within the box holding data in a specified format. So, plain text is just a plain-text section. "Rich text" is usually represented as HTML, with embedded "pointers" to other sections containing embedded objects, such as images or attachments. Other data, such as file attachments, reside in their own sections, with their own "headers" specifying size, encoding (e.g., base-64) and format (e.g., JPEG or GIF). The different sections in the MIME file are separated by "boundaries", essentially a unique string. There's much more to it, of course, but these are the basics.

What if you want to write script (LotusScript, Java, other) to programmatically convert Notes documents to MIME format? If you're using a recent (v8.5x) version of Notes or Domino, then most of the work is done for you with new methods in the back-end classes. This functionality is, of course, based on entry points in the Notes C API. If you're not using LotusScript or Java, you can accomplish MIME translation with a C or C++ program using these entry points, or, even easier, use the COM classses. I'll discuss how to do MIME conversion using the C and COM APIs in Part Deux of this post.

Here's a basic Java program showing the essential techniques for conversion. I'm leaving out all the surrounding code for acquiring Document objects, preparing FileOutputStreams, and so on. There is only one slightly tricky thing about this program, which we'll get to after this first section.

Session session = NotesFactory.createSession();
// turn off automatic mime conversion on document open
// if doc is already in MIME, leave it so
session.setConvertMIME(false);
Document doc = .... // get document somewhere
// kill any $KeepPrivate items
doc.removeItem("$KeepPrivate");
doc.convertToMIME(lotus.domino.Document.CVT_RT_TO_HTML, 0); // note: Designer doc has wrong spelling
WriteOutputMIME(doc);

So far, so good. We suppress automatic conversion on document open, to save work (if the document is already in MIME format, we can skip the convert step and just write it out). If the "$KeepPrivate" item is present in the document, conversion will fail, so we remove that. Then all we do is call the Document.convertToMIME() method, specifying that we want rich text converted to HTML.

After the convert call, the document in memory is now a sequence of items containing MIME headers, and a (possibly multi-part) body representing the rich text body of the original document, plus any attachments it contains. We can (almost) proceed to iterate over these items and write them out to disk (or wherever).

I say "almost", though, because there's a glitch in the conversion code deep underneath the C API layer: it does not automatically convert attachment contents to a base-64 encoding (even though the API documentation says it will) - it leaves them in binary format, which cannot be written to disk. So, we have to look for those items, and force them to be converted to base-64 text. This next section of Java code for the WriteOutputMIME() functions shows how to do that. Again, I've pared the code down to the essential bits:

private void WriteOutputMIME(Document doc, File outDir)
throws Exception
{
File outFile = null;
MIMEEntity mE = null;
MIMEEntity mChild = null;
String contenttype = null;
String headers = null;
String content = null;
String preamble = null;
int encoding;
FileWriter output = null;
String noteid = doc.getNoteID();
int index;

// access document as mime parts
mE = doc.getMIMEEntity("Body");
outFile = new File(outDir, noteid + ".eml");
output = new FileWriter(outFile);

try {
contenttype = mE.getContentType();
headers = mE.getHeaders();
encoding = mE.getEncoding();

// message envelope. If no MIME-version header, add one
index = headers.indexOf("MIME-Version:");
if (index < 0)
output.write("MIME-Version: 1.0\n");
output.write(headers);

// for multipart, usually no main-msg content
content = mE.getContentAsText();
if (content != null && content.trim().length() > 0)
{
output.write(content);
output.write("\n");
}

// For multipart, examine each child entity,
// re-code to base64 if necessary
if (contenttype.startsWith("multipart"))
{
preamble = mE.getPreamble();
mChild = mE.getFirstChildEntity();
while (mChild != null)
{
headers = mChild.getHeaders();
encoding = mChild.getEncoding();

// convert binary parts to base-64
if (encoding == MIMEEntity.ENC_IDENTITY_BINARY)
{
mChild.encodeContent(MIMEEntity.ENC_BASE64);
headers = mChild.getHeaders(); // get again, because changed
}

preamble = mChild.getPreamble();
content = mChild.getBoundaryStart();
output.write(content);
if (!content.endsWith("\n"))
output.write("\n");
output.write(headers);
output.write("\n");

content = mChild.getContentAsText();
if (content != null && content.length() > 0)
output.write(content);
output.write(mChild.getBoundaryEnd());

mChild = mChild.getNextSibling();
} // end while
} // end multipart

// end of main envelope
output.write(mE.getBoundaryEnd());
}
finally {
if (output != null)
output.close();
}

} // end WriteOutptuMIME

So, a little tricky, but not too bad. You have to get the boundaries right, as well as the line breaks. Otherwise, it's really just copying stuff out to disk. Remember that the message has some overall headers (mE.getHeaders()), and each child entity has its own header section as well, describing what's in that chunk of data. When we re-code an entity from binary format to base-64 format, we need to re-read the entity headers, because they'll reflect that change.

A final comment about HTML conversion: it theoretically existed back in R5 (you know what they say about "in theory"...), but it didn't start working well for real until v7.03. And it has been improving ever since, so the later the version of the product you have, the better off you'll be.

In my next blog post (part deux), I'll show you how to adapt this basic code for the Notes COM classes, where (for some stupid reason) the Document.convertToMIME() function does not exist). We will not be thwarted! I'll show you how to use the Notes C API from a C-sharp program to do the MIME conversion.

Happy coding! Geek ya later!

Using Fiddler to monitor HTTP traffic in Domino Java agents

Bob Balaban — Mon, 14 Mar 2011 04:15:00 -0400

Greetings, Geeks!

If you're writing Domino Java agents that use HTTP requests to talk to the Internets, you might need to debug your code by capturing the actual bits that leave your computer as Web requests, or even by looking at the responses that come back.

I recently had to do just that for a customer project. I could write debug logs for the URLs and "payloads" that I was sending and receiving, but you don't easily get to see the HTTP headers that come and go. I found that I could download and configure Fiddler (it's free here) to reveal all, for both "normal" HTTP and also for HTTPS connections.

First of all, if you're debugging Java agents for Notes or Domino, I hope you're doing it in Eclipse, as described in my "2-Headed Beast" posting.

There's only 1 little trick you need to know to make it work properly. Because Fiddler acts as a "proxy", inserting itself between your program and your network you have to tell Java to send HTTP commands to Fiddler, instead of directly to your network adapter (other programs, like the Chrome client for GMail automatically look for proxies, and require no special configuration). The way you tell Eclipse to do what you want is to go to the "Run Configuration" (or "Debug Configuration") dialog, click on the "Arguments" tab, and enter these JVM arguments into the "VM arguments" box:

-DproxySet=true -DproxyHost=127.0.0.1 -DproxyPort=8888

Click "Apply", and you're all set. Launch Fiddler before you run/debug your code, and it will capture all the HTTP traffic out and in. Click the "Raw" button in Fiddler to see everything (outgoing in the top pane, incoming in the bottom pane), including headers. Voil�! It's especially fun to use with Web Services.

What about doing this in Domino Designer? I haven't found an equivalent setting that allows me to specify the extra JVM arguments that Fiddler needs. It may be that if you can tweak the Run Configuration for your agents in Designer (see my blog post on how to do that), you can get it to work - I haven't tried it.

What about LotusScript? Well, unfortunately, LotusScript has never had native HTTP capabilities (probably never will). Most people who want to use HTTP from a LotusScript program use outside libraries that you can invoke using DECLARE statements, or (on Windows systems), use the COM interfaces to libraries such as MSXML.

Well, there you have it. Happy coding! Geek ya later!

Backup your GMail account to NSF

Bob Balaban — Mon, 28 Feb 2011 12:15:14 -0400

Greetings, Geeks!

I read with concern the recent reports of some GMail accounts disappearing, as I use a couple of them for business and other purposes. I thought about writing a program to download all my mail and store as backup in a Notes database, but then I remembered that Notes already has a built-in feature for doing that: IMAP integration.

It took me 5 minutes to set it up and download over 7000 messages from my (thankfully still operating) GMail account. It even converted GMail "labels" into NSF folders.

So, here's how you do it (I used Notes 8.52, I think it works in v7 as well):

1) Go to your local Contacts database (ooops, I mean "Application"!), names.nsf
2) Click on "Advanced" in the navigator, then "Accounts"
3) Create a new Account document
4) Name it anything ("gmail")
5) "Account server" is "imap.gmail.com" (don't enter the quotes)
6) Login is your GMail account name, including the @gmail.com part
7) For Protocol I used "IMAP online". I didn't experiment with the "IMAP offline" feature, but I suspect it adds your gmail mailbox to the replicator page for background sync. Maybe someone can confirm/deny
8) I changed the SSL setting to "Enabled", because I have my GMail account set up to use SSL

So far so good, Notes creates a new NSF for IMAP sync. When you open it, Notes goes out to the IMAP account and synchronizes. First time I tried it, though I got an error "Invalid SSL certificates".

I fixed that problem by going back into the Account document, and going to the "Advanced" tab. I changed the "Send SSL certificates when asked" option to "Yes". I also changed "Accept SSL site certs" to "Yes", though I don't know if that's required or not.

Works great! Thanks Notes!

Geek ya later

Geek-o-Terica 14: How Using "LimitEntries" Can Mess Up Db Replication (Unintended Side-Effects)

Bob Balaban — Fri, 18 Feb 2011 16:25:00 -0400

Greetings, Geeks!

This one is going to get uber-geeky real fast, so hang onto your gaming consoles.

We need a little background, but I'll keep it brief. Most of you probably know that whenever a document is saved (written to disk in the NSF), 2 list items automatically get updated: $UpdatedBy is a list of the names of the people who modified (and, initially, created) the document. The $Revisions item is a list of date/time values indicating the times at which the updates occurred. So, these 2 lists are "parallel", in that the last name in $UpdatedBy can be assumed to have modified the document at the last date/time in $Revisions, and so on, back into history, as far as it goes.

Somewhere back in the V4/V5 days, people started to notice that these lists could, over time, get pretty big. A new Distinguished Name (10-30 characters) plus a new date/time value (8 bytes) each time someone hits Ctl-S in a document can start to add up. Even small documents could end up bloated by "bookkeeping data". So someone invented two new properties in the Application (nee Database) Properties box, on the propeller-hat tab: "Limit Entries in $UpdatedBy fields" and "Limit Entries in $Revisions fields". By default, these settings have a value of zero, meaning (as usual), "no limit". But, should you desire, you can set these properties to non-zero values to keep the size of your documents from growing forever. Of course, it's nice if you set the 2 properties to the same value, to keep the 2 lists in "sync", but you're not forced to (is that recommendation even documented? I didn't check).

Ok, so far so good. But, you ask, what does this have to do with replication? Aha! Well, first just a bit more background.

Before Notes v4, there was only 1 replication granularity: full document. The replication logic matched up the documents in 2 NSF replicas by their UNIDs (Universal IDs). If one document's "last-modified" time is later than the others, then (keeping it simple here by skipping some gritty details) it "wins". That worked fine for quite a while, but it meant that the replicator had to copy the entire document from one NSF to another when one copy of the document had been modified, and the other hadn't. If the document contained 10mb of attachment data, well, tough, the replicator copied all 10 mb, because it had no way of knowing whether the attachment itself had been modified.

Enter "Field Level Replication", somewhere in the V4 timeframe. (By the way, you may -- or may not -- be surprised to know that "replication" was never patented by Lotus or Iris. However, Field Level Replication was patented in the early 1990s). This is an optimization applied to the normal replication logic that allows for much greater efficiency, but it required a change to the on-disk representation (ODS) of documents. The key innovation in FLR was that a new C API entry point was created that could tell a caller (for example, the Replicator) the date/time of last modification of a single DATA ITEM in a given document. This new entry point allowed the replicator to enhance it's normal logic to say something like: "Ok, DocA and DocB are the same (same UNID). DocA has a later last-modified date. But I may not have to copy the WHOLE document to DocB's NSF. I can match up the pair-o'-docs item by item, and only update DocB with the items that are modified!"

Clearly better when you've got a big replication with lots of changes. But, how does the item-last-modified API actually work? You certainly don't want to store a full 8 bytes of date/time data for each item in a document, that's an enourmous use of space. Instead, someone figured out that they could use only 3 or 4 bits to store an INDEX into the list of document last-modified dates for each item. My recollection is (I could be wrong about this) that the number is the count from the END of the $Revisions list. So, a "1" probably means "last entry in $Revisions", etc. Cool, huh? Clever! You get huge new functionality by spending only a few bits per data item.

BUT! What if someone's set the db property to "Limit Entries in $Revision fields"?? What if (extreme case here) there are only 2 entries allowed, but items in some document have been modified 3 or 4 times in one replica, and not at all in another? Aye, there's the rub.

The answer is, you lose field-level replication for that document, and any others like it. The "get me the item last-modified time" logic has to account for that, of course, and there's really only one thing it can reasonably do. If the last-mod "index" attached to an item is bigger than the length of the $Revisions list, it has to fall back to document last-modified time, because the last-modified time of the document is guaranteed to be greater than, or equal to, the last-modified time of any item in that document.

So, there you have it: an unintended consequence of limiting the amount of $Revisions space used in a document is that you make replication run slower (in some situations). "Correctness" is not violated (important point!): you never lose data as a result. It's just that in some cases replication will take longer. How much longer? It depends on your data. So, as always, it's a trade-off, space vs. time.

Hope this helps, Geek ya later!

Presenting at "IDoSphere" - Debug Domino Java Agents With Eclipse

Bob Balaban — Wed, 9 Feb 2011 07:34:34 -0400

Greetings, Geeks!

Suffering from post-Lotusphere let-down? Never fear, sign up now for "IDoSphere"!

It's cheap, it's got great content, and it's all online, no need to leave the comfort of your own desk. Register HERE for the special 10% discount, use the coupon code IDS2011BB

My session is:

Debugging Notes Java Agents With Eclipse
There is still no Java debugger (that humans can use) built into Domino Designer. If you want to build a complex Notes or Domino agent using Java, how can you debug it without making major code changes between debug and production modes? Come to this session to learn how to use a technique called the "2-Headed Beast" - a way of writing a Java program so that it can be run both in debug mode from within Eclipse, and then pasted into Designer with zero code modifications. This session assumes a working knowledge of Java, but you need not be a guru to make friends with the 2-headed beast!

I'm doing this live-in-the-studio with live Q&A.

http://bit.ly/IdoSphereDiscount
IDS2011BB

Geek ya Online!

Geek-o-Terica 13: Notes Response Hierarchies - Without Views

Bob Balaban — Mon, 6 Dec 2010 00:01:00 -0400

Greetings Geeks!

So. Everyone who's written any interesting amount of LotusScript (or Java) code in Notes or Domino has done the whole "get a view, get a document, get the first response to that, travel the (possibly deeply nested) response hierarchy..." thing. Probably more than once. It can be tedious, and you often have to create special views in your app that are used only for code navigation, which can blow up the size of the NSF. Yes, you can use the NotesViewNavigator class to manage categorized and nested views, it's a great piece of functionality. However, I have found that in large databases (4gb+), with complex views, the ViewNavigator class can be pretty slow to set up and use.

Is it possible to figure out response hierarchies without using a view at all? Yes, it sure is! You can navigate response hierarchies just using features in the NotesDocument class.

But first you have to make sure the database itself is set up to support that. Go to the properties box, and to the "propeller beanie" tab (this screenshot is from Notes 7):

Make sure that the double-negative "Don't support specialized response hierarchy" is NOT checked.

To explain how this works, let's start with the basics of response documents. A document is a response to another document (it can only be a response to one other document, or not at all) if it contains a data item named "$REF", and that item contains the UNID of the "parent" document. That's it, very simple. The parent does NOT (in the document itself) contain a list of "child" documents. When documents show up in a View that has response hierarchies enabled, the view display logic figures out all the parent/child/child-of-child relationships based purely on the $REF pointers. No special support from the NSF layer is required.

But if you don't disable the "specialized response hierarchy" feature in your database, then NSF is also, quietly and robustly, perhaps without you even realizing it, keeping track of which documents have $REF items and to what other documents they refer. And (the important point), this information is available through the Notes C API, and, as a consequence, is also available in the LotusScript and Java Document class.

How do you do it? Simple! Use the NotesDocument.Responses property. It returns a NotesDocumentCollection object containing all of the first-level responses to the current document (if there are any). You can then follow the nested hierarchy (if there is one) by extracting each document object from the collection and getting its Responses list in turn.

Not quite as convenient as using NotesView or NotesViewNavigator getfirst/getnext calls, but there are a couple of advantages to doing it this way:
- You might be able to reduce the number of views in your NSF, which saves disk space and also results in better performance at NSF indexing time
- If your response hierarchies are relatively simple (e.g., only 1 level of responses), this technique is quick and easy to code

Is it for you? Only you can make that determination. Try it out and see!

Happy coding! Geek ya later!

Geek-o-Terica 12: Finding databases by Replica ID vs. by path

Bob Balaban — Sun, 14 Nov 2010 01:43:55 -0400

Greetings, Geeks!

Everyone who writes application code (LotusScript or Java) in Notes/Domino uses Session.GetDatabase(, ), if not all the time, then at least frequently. I haven't done a "Geek-o-Terica" post in a while, so this seems like a good topic with which to revive the series.

First of all, let me state that this article is NOT about whether you should use hard-coded database server/path names in your code, because you shouldn't, end of story. Why not? Because databases can (and do) move. An NSF that your app assumes is in a particular folder today might be somewhere else tomorrow (ah, those pesky admins, shuffing things around on the server again). It might even get moved to a different server. The last thing you want to do is modify your code when something moves, it can get ugly (and if you have real change processes in place, you'll have to re-test everything too).

If you have code that refers to databases that are not the current one (i.e., not Session.CurrentDatabase), then the best practice is to use a Profile Document to store the outside database's server and path. That way, if it moves, you only have to update the Profile Document (via a form) with the new location.

What I really wanted to talk about was the "best practice" (in quotes, because this is not necessarily a settled issue, as you'll see) for actually getting the outside database in your code. Most people don't really think about it much, they just provide the server name and the db path (hopefully from a Profile Document or other external source). But, there is another way it can be done, and in some cases, it's better. And that is, look up the database by it's Replica ID instead.

First, how do you do that? The code pattern is easy, you just use the Database.OpenByReplicaID() function. Here's a sample from the Designer Help doc: Dim db As New NotesDatabase( "", "" ) If db.OpenByReplicaID( "Moscow", "85255FA900747B84" ) Then Print( db.Title & " was successfully opened" ) Else Print( "Unable to open database" ) End If

There are a couple of things about using this call that are inconvenient relative to just using Session.GetDatabase() or New Database():

- You have to instantiate the db object first, then open it (more typing)

- You have to get and store the replica ID (e.g., in a Profile document, also more typing), because of course you wouldn't hard-code a replica id any more than you'd hard-code a db path, right? Right?

However, the big advantage of using the replica ID is that you don't have to know (or care) where on the server the database might be located. Given the replica ID, the server (or the Notes Client) figures out where the physical file is, and opens it for you. This doesn't eliminate the need for a Profile document in your app, as you still need to store the server name and the ID itself somewhere, but it does simplify things a bit. because if some pesky admin moves your database without telling you, you don't even have to update your Profile document. You can just laugh at them and say "Do your worst! I care not! Hahahaaa!" (actually you might not really want to say "do your worst", they might take it as a challenge...)

There is, however, one drawback to using the replica ID technique that makes it unusable in some cases, and that has to do with failover.

If your database is on an clustered server, you may well want to access it from your code in such a way that if the server you specify is down, you can automatically "fail over" to another server in the cluster, and get a replica of the database you specified. The way you normally do that is as follows:

Dim db As New NotesDatabase( "", "" ) If db.OpenWithFailover( "Moscow", "sales.nsf" ) Then Print( db.Title & " was successfully opened on server" & db.Server ) Else Print( "Unable to open database" ) End If

This is nicely transparent, in that (if possible) you get a database object that references your db, whether it actually lives on the server you specified, or on another server in the cluster (the call works even if the server is not clustered). The Database.Server property reflects the server the database was actually opened on, and therefore might be different from the one you specified.

You may have already spotted the problem with this: there's no way to open a database with failover by specifying its replica ID. This is a design flaw, going all the way back to Notes 4, simply never got plugged. Partly that's because of the way the Notes C API is set up (both the LotusScript and Java interfaces depend on the C API to do the real work), and partly it's just an oversight. Unfortunately, it means that if you want to use replica IDs to get a database in LS or Java code, you can't take advantage of failover behavior. And if you want failover, you can't get databases by replica ID.

Happy coding! Geek ya later!

(Need expert application development architecture/coding help? Want me to help you invent directory services based on RDBMS?? Contact me at: bbalaban, gmail.com)
Follow me on Twitter @LooseleafLLC
This article �Copyright 2010 by Looseleaf Software LLC, all rights reserved. You may link to this page, but may not copy without prior approval.

Busy 2 Weeks: ILUG and DNUG

Bob Balaban — Sun, 7 Nov 2010 04:11:30 -0400

Greetings, Geeks!

Welcome to USian Standard Time (1 hour earlier in most states).

I'm off later today for an 11-day swing through Northern Ireland (note proper spelling as supplied by Mr. Steve McDonagh: "Norn Iron") and Germany for ILUG2010 and DNUG.

ILUG continues its tradition (and I believe it was the first to establish this tradition) of having people attend for free: the sponsors pay the freight. The conference is organized and staffed by volunteers. It's a terrific event, and will mark my first ever visit to Belfast.

My session at ILUG will be:

Deconstructing Web Services: How Do They Really Work, and What to Do When They Don't
SOAP-based Web Services hosting (in Domino) and consuming (in Notes) is really great: easy to use, robust and powerful. That is, if you carefully stay within the (mostly documented) boundaries of the functionality it handles well. But what happens when you try to do things that "should work", but don't? We're not talking about bugs here, but functionality outside the scope of what Notes and Domino implement. How do you detect that? And having detected it, what do you do about it? And how does all this Web Services stuff REALLY work, anyway? Come to this session to discover the technology building blocks of Web Services (design time and runtime), and see some examples of how you can work around the bits that may not do what you need.

DNUG is a conference I have spoken at many times over the past 11 years. It still amazes me that they can put on two quality technical conferences per year, every year. I'll be attending some panel discussions and presenting two sessions in Frankfurt:

"Cloud" Computing with Notes: Using Google APIs to get stuff done
If you're like many, many people these days, more and more of your data (email, calendar entries, documents, photos, YouTube videos...) are living somewhere in the world on a server owned by Google. What if you want to write Notes or Domino apps that "reach out" to the Google cloud? Is it possible to store, access, synchronize your Google assets from a Notes agent? The answer is "YES!" All of Google's services are accessible via XML-based REST APIs over HTTP, and Google has provided some nice, client-side object-oriented class libraries for us to use.
If you’re nervous about letting Google hold all your data, or if you just want to learn something about REST APIs and object-oriented web services interfaces, come to this session to see some cool demos, and learn how to get started with your own Google code.
While this session is mostly for developers with some experience with Java, anyone interested in the architecture and functionality of REST and Google will find something to learn.

and

How to make a software development project fail
Anyone can make software projects succeed, but it takes special skill to make them reliably fail, time after time.
Come to this session to learn the secrets of guaranteed failure, such as: sabotage staffing, reduced-resourcing, goofy goal-setting, ridiculous rewarding and mangled management. Learn how to save money, assign blame and trash teams. These techniques will serve you especially well if you are in business to produce and sell anti-social software or un-collaborative systems.
You will benefit from this session if you are a manager or leader of development teams. The less skill you currently have in destroying software projects, the more you will learn! Attendees who know anything about writing code will probably know less when they leave than when they arrived.

That latter one should be especially interesting :-) Hope to see you there!

How to get ALL of the documents: db.search() vs. db.AllDocuments vs. AllDocuments view

Bob Balaban — Mon, 25 Oct 2010 04:00:00 -0400

Greetings, Geeks!

Have you ever had to write an agent that looks at ALL of the documents in a database? As is usual with LotusScript/Java and the back-end classes in Notes, there's more than one way to do that.

Actually, there are (at least) 3 common techniques:
1) Database.AllDocuments
2) Get the "All Documents" view and iterate
3) Database.search("@all")

I used to always use (and recommend) Database.AllDocuments, which returns a DocumentCollection instance. It's very efficient, because it maps to an optimized C API call that retrieves a list of all NOTEIDs (as an IDTable) in the database. This translates to a LotusScript DocumentCollection instance very easily, and none of the document objects is actually "opened" until you access it from the DocumentCollection,

Then, somewhere along the way, I discovered that a change had been made to the behavior of this property. Originally (Notes 4.x), the code in the back-end classes implementation filtered out any deletion stubs in the IDTable resulting from the C API call. Again, this was an efficient operation, made possible by the fact that the NOTEIDs of deletion stubs all have a high bit set (0x80000000L). So you could tell the API to remove all values in the IDTable greater than 0x80000000L, and what was left would be all valid NOTEIDs.

At some point (not sure when, or why), this final filtering operation was removed. So now, if you use Database.AllDocuments, you might find that as you iterate through the document objects in the result set, some of those documents will be "invalid" or deleted. It can be hard to work around this in your code, as the DocumentCollection.getNextDocument() call does not usually work if the "current" document object is invalid. See here and here for some of the details.

I recently worked on a project where the speed of acquiring all the document objects in the NSF and iterating through them was really important. The AllDocuments/GetNth technique was too slow. So I thought I'd try iterating through the "All Documents" view instead (this particular project was processing dbs derived from the standard mail template). I thought it would be pretty fast because all the indexing would have already been done, and it was fast. The problem, however, was that it didn't really retrieve ALL of the documents in the database. Why? Here's the mail template "AllDocuments" view selection formula (the "($All)" view):

SELECT @IsNotMember("A"; ExcludeFromView) & IsMailStationery != 1 & Form != "Group" & Form != "Person"

So any document that has a field "ExcludeFromView" containing an "A", or any document with a Form field containing "Group" or "Person", or any mail stationery document would never show up in the "All" view, and your agent would never see it. For some purposes this would be fine, but not for the project I was doing at the time, I really needed ALL of the documents.

So I fell back on Plan C: do a Database.search using "@all" as the selection criterion. I thought it would be slow, because the search() function visits every document in the database to apply the @function selection formula. But I knew that it would also explicitly exclude any deletion stubs from the result set, and that was a major concern. It turned out that the search was not particularly slow, certainly it's faster than using DocumentCollection.GetNthDocument() on a very large (100K) result set. The performance overall was actually pretty reasonable, and since I know that the resulting DocumentCollection will not contain any deleted documents, I can avoid GetNthDocument and just use GetFirst/NextDocument.

So, there you have it. All 3 techniques "work" (with variations in behavior), you need to think carefully about which one you should use.

Geek ya later!

"32K limit exceeded", huh?? Why SUMMARY is not always your friend

Bob Balaban — Wed, 20 Oct 2010 16:41:37 -0400

Greetings, Geeks!

So there I was (don't you love stories that start out that way?). I was writing an agent to take journaled email messages, expand group names in the various recipient lists (SendTo, CopyTo, etc.), and then save a copy of the message with expanded lists in another database.

The group expansion issue was a little tricky, because Notes lets you nest group names (an email or security group can include the name of another group). That was fun to solve, maybe I'll post that code sometime. BUT, in testing, it turned out that if an expanded recipient item got too big, Notes would throw an exception (I was using Java) on the Document.save() call, "32K field limit exceeded". What? B-b-b-but I SPECIFICALLY coded the agent to watch how long the field is getting....

Ok, background: The limits I always knew about were pretty straightforward: No single data item, of any type, can be bigger than 64KB (and that includes overhead for type codes and stuff). The CAPI documentation says you should really limit the size to 40KB, plus or minus. "SUMMARY" items (those which can appear in a View) have to be 15KB or less in size. Rich text items can be any size, but that's because when a single item containing rich text data gets too big (more than 40K or so), Notes just creates another item of the same name and tacks it onto the chain of data items that make up the document.

My group expansion processing yields a Vector containing a String object for each name in the recipient field. Vectors can be any size, no problem). In order to obey the Notes limits, though, I chose to create a "recipient list" Vector, and add name to it from the original Vector, counting the length of each String as I add it, until I hit my 40K (or so) limit.^**Then I can just take the new Vector and hand it to Document.replaceItemValue(). If I fill up the original field name (this is in the copy, of course, not in the original journal message), I start a cascade: SendTo_1, SendTo_2, etc., until I've used up all the names in the expanded list. No single item has more than my pre-defined maximum of 40K characters (String.length returns number of characters, remember, NOT number of bytes! Pay attention, this might be important later).

So, why, after doing all this work to keep the translated items short enough for Notes, do I get the "32K limit exceeded"?? At first I thought it was because i was counting characters in Java, not bytes. Each character in a Java String object (which is normally encoded as UTF-16) actually consumes 16 bits, or TWO bytes, not one. So a 40Kchar string is actually using up 80KBytes! But.....no. Because when I pass the String objects to Notes, Notes automatically translates each one to LMBCS (the internal Notes character set, see my character set tutorial here for a full explanation), which is mostly 1 byte per character (not for Kanji and other multi-byte character sets, but in this case that's not what I was dealing with).

Ok, so....whatever. I dialled the max item size down to 30K and ran it again. Same error. Crap.

So then I did what I often do when I'm really, really stuck. I called my friend Daniel. We brainstormed. To make a longish story short-ish, he made a suggestion which, although it sounded a little weird, actually WORKED (he's very good at that).

The key was: Turn OFF the SUMMARY flag on the new items. Here's an approximation of how I did that in my Java code?

Vector expanded; // the expanded list of names. We get that in other code I'm not showing you today. List of String objects
Vector newField; // the list for a single document Item we're going to build, and track the length of
int newLength;
String nextOutputItem; // name of next item to write to the document

// skipping details of outer loop over recipient fields....
// do a loop over names for the next output item
// (skipping tedious logic about cascading output items when they get too big...boring)
newLength = 0;
nextOutputItem = "";
for (int i = 0; i < expanded.size(); i++)
{
String aName = (String) expanded.elementAt(i);
if (newLength >= MAX_LEN_WE_MADE_UP_SOMEWHERE)
{
// current newField is full, write it out
// MUST turn off the SUMMARY flag before doc save
Item newItem = doc.replaceItemValue(nextOutputItem, newField);
newItem.setSummary(false);
nextOutputItem = "";
}
else {
newLength += aName.length();
newField.append(aName);
}
} // end for i

Ok, I hope you get the basic idea. replaceItemValue() returns the Item object (convenient), so just use it to turn off the SUMMARY flag. Then when you save the document, you don't get that nasty 32K error.

BUT, the question remains: WHY does this work? We haven't reduced the size of the items we're writing. And if the limit for SUMMARY items is 32K, why did we still get the error when we starting limiting the items to 30KB??

I'm afraid, my friends, that the answer has to be: The error message is wrong. Bogus. Full of it. Misleading, at best. There IS NO 32K LIMIT!! 14K (or so) limit, maybe. THAT's why turning off the SUMMARY flag works, we're telling Notes that the item content is allowed to go all the way to 64KB (or so).

So, there you have it. Go forth and code, with no pesky, wrong error messages to befuddle and comfusticate your day.

Geek ya later!

** "Got the Vector, Victor?" (Lord, I just love the movie "Airplane"...)