Lotusscript

LotusScript for HCL Domino

LotusScript is the scripting language for HCL Domino (formerly IBM Lotus Notes/Domino). It resembles Visual Basic but has critical differences. Target platform: Domino 14, backend classes only (web-based applications).

CRITICAL: LotusScript Is NOT Visual Basic

Claude frequently confuses LotusScript with VBA/VB6. These differences will cause broken code if ignored:

Scope: Backend Classes Only

This project uses Domino as a web application server. All code runs in agents and script libraries triggered by HTTP requests. Never use front-end (UI) classes:

• DO NOT USE: NotesUIWorkspace, NotesUIDocument, NotesUIView, NotesUIDatabase
• USE: NotesSession, NotesDatabase, NotesDocument, NotesView, etc.

Web Agent Essentials

Sub Initialize
    Dim session As New NotesSession
    Dim db As NotesDatabase
    Dim doc As NotesDocument

    Set db = session.CurrentDatabase
    Set doc = session.DocumentContext  ' CGI variables and POST data

    ' Read query string
    Dim queryString As String
    queryString = doc.GetItemValue("Query_String_Decoded")(0)

    ' Output HTTP response
    Print "Content-Type: application/json"
    Print ""
    Print |{"status": "ok"}|
End Sub

Key web agent rules:

• Print writes to the HTTP response body — first print Content-Type, then a blank line, then body
• session.DocumentContext provides CGI variables as fields on a document
• Pipe | characters delimit strings that can contain quotes
• Web agents run as the authenticated user (or Anonymous for unauthenticated)

Common Gotchas

1. GetItemValue returns a Variant array — always index with (0) for single values
2. Save is not automatic — always call doc.Save True, False after modifications
3. Nothing checks — always check If Not (doc Is Nothing) before using objects
4. String comparison — use StrCompare or LCase$() for case-insensitive comparison
5. Arrays are 0-based by default — use Option Base 1 to change, or use LBound/UBound
6. Lists vs Arrays — Lists are associative (keyed by string), Arrays are indexed by integer
7. Variant vs typed variables — always use Option Declare and type your variables
8. RichText fields — cannot be read with GetItemValue, must use GetFirstItem and cast to NotesRichTextItem
9. Date handling — use NotesDateTime objects, not native date functions, for Domino date fields
10. Chr(0) is CRLF — in Domino, Chr(0) acts as Chr(10)+Chr(13) (newline), not a null byte as in standard ASCII. Long-standing Domino behavior since the 1990s.
11. Large POST bodies are chunked — Domino splits large Request_Content into numbered fields (request_content_000, request_content_001, etc.), each ~32-64K depending on platform
12. NotesHTTPRequest.ResponseCode is a String — returns the full status line (e.g., "HTTP/1.1 200 OK"), NOT an integer. Use InStr(http.ResponseCode, "200") > 0 to check status — never http.ResponseCode = 200

Reference Files

• syntax-fundamentals.md — Data types, control flow, error handling, strings, arrays, Lists
• domino-object-model.md — Backend class hierarchy and usage (NotesSession → NotesDocument)
• domino-modern-features.md — Domino 10-14: DQL, JSON classes, HTTPRequest, LS2J, MIME
• web-agent-patterns.md — Web agent patterns: CGI vars, JSON output, CRUD, error handling