#Formula
Posts tagged #Formula · 17 posts
- Running @Formula from SSJS: session.evaluate — Its Vector Return, Limits, and Why It Can't Change a Document
You already have Formula logic — an @DbLookup, an @Name formatting call — and you don't want to rewrite it in SSJS. session.evaluate() runs a Formula string straight from SSJS and hands the result back. But it has sharp edges: it returns a java.util.Vector (not a scalar), field references need the document as a second argument, UI @functions (@Command/@Prompt/@PickList…) don't work in it, and it can't change a document — only compute a result. This covers the two signatures, the return and limits, and how to write the result back when you need to persist it.
2026.10.05 - @Prompt and @PickList: Formula Dialogs to Ask the User — Client-Only, Not on the Web
Want a button to pop 'Are you sure you want to delete?', or let the user pick a customer from a view? In Formula that's @Prompt and @PickList. @Prompt has a whole set of styles (Ok / YesNo / OkCancelList / Password / LocalBrowse…); @PickList opens a modal to select documents from a view and returns a column value, or to pick names from the Directory. But run the same formula on the web, or in a scheduled agent, and it silently does nothing — HCL states plainly, 'You cannot use this function in Web applications.' This covers the styles and return values, the client-only boundary, and which to use.
2026.10.02 - @Command vs @PostedCommand: Why Your Formula Doesn't Run in the Order You Wrote It
You compute a field, then call an @Command to do a UI action — and the action runs first, your computation second. Here's why: @Command mostly runs in the order you wrote it, but @PostedCommand always defers until after every other @function finishes, so a @PostedCommand at the top of your formula runs last. Worse, some @Command functions are themselves deferred. This uses the official order-of-evaluation rules to explain the difference, which @Commands are inherently deferred, and when to use which.
2026.09.29 - @SetEnvironment and SetEnvironmentVar: Those "Environment Variables" Live in the notes.ini of Whatever Machine Runs the Code
To stash a setting from Formula or LotusScript, you've got a pile of look-alikes: @SetEnvironment, @Environment, session.SetEnvironmentVar, GetEnvironmentString. What they actually read and write is the notes.ini of the machine running the code — per-machine, not shared, not replicated. Plus a $-prefix rule that trips people up (Formula and LS prepend $ by default; reading a native notes.ini setting needs a flag). This piece pins down where they write, where the $ comes from, when to use them, and when to switch to a profile document instead.
2026.09.22 - NoteID, UNID, @DocumentUniqueID: What Actually Separates Domino's Three Document IDs
To point at a Domino document you might grab its NoteID, its UniversalID (UNID), or use @DocumentUniqueID in Formula — three that look alike and behave nothing alike. A NoteID only means something inside one database file and changes across replicas; the UNID is a 32-character identity that's identical across every replica; @DocumentUniqueID returns that UNID (but without @Text it's a doclink, not text). This piece pins down each one's scope, stability, and when to use it — including the 'change the UNID and it becomes a new document' and 'save a duplicate UNID and get error 4000' traps, and where that /0/UNID in web URLs comes from.
2026.09.14 - Classic Domino Web Attachment UI Tricks: Hide the Crude Default with $V2AttachmentOptions, Then Draw Your Own List and Delete
Drop a File Upload Control on a Domino web form, add a save button, and it works — but it looks crude: Domino dumps the attachments at the bottom of the page, and in edit mode adds a row of un-styleable 'mark for deletion' checkboxes. This piece covers the classic Domino web developer's toolkit: hide the default attachment area with $V2AttachmentOptions="0", draw your own download list with pass-through HTML and @AttachmentNames, and the rarely-explained delete mechanism %%Detach (roll your own checkboxes, or use WebQuerySave). Includes the gotchas: $V2AttachmentOptions is 0/1 only, and it's text not a number.
2026.09.11 - Formula's @For Loop: When You Actually Need It, and a Real 'Reverse an Org Hierarchy' Example
The list functions (@Transform, @Explode…) handle a whole list in one line, but some jobs still need a real loop — accumulate state, build a string in order, reverse a list. This piece goes deep on @For: the four parts (initialize/condition/increment/body), a thing that trips people up (@For returns 1, not your accumulated value, so you return the variable on a separate final line), and a real need worked through — turning an A\B\C org hierarchy into C\B\A. Plus how @While/@DoWhile differ, and the infinite-loop guard.
2026.09.01 - Error Handling and Evaluation in Formula: @IfError, @Eval, and Where a Formula Runs
Series finale. The first six parts covered what formula can do; this one covers two things you hit no matter what you write: what happens when a formula errors, and where and when a formula actually runs. Catch errors with @IfError and a fallback, test with @IsError — but remember @IfError hides the real error message, so drop it while debugging. @Eval runs a string as a formula at runtime. And 'which context a formula runs in' is the root of half the series' gotchas (@DbLookup not allowed in column formulas...). Part seven (final) of the Formula @function series.
2026.08.31 - Control Flow and Variables in Formula: :=, @If, @Do, @For/@While
A real formula branches, holds intermediate values, and occasionally loops. This piece covers structuring formulas: temp variables x := ... are the modern backbone (semicolon-separated, the last statement is the return value); @If chains up to 99 condition/action pairs — formula's switch; @Do evaluates in sequence and returns the last; and real loops @For/@While/@DoWhile exist but, because formula is list-oriented, are rarely needed. Part six of the Formula @function series.
2026.08.30 - Date Arithmetic in Formula: @Adjust to Add/Subtract, @Now/@Today for Now, and @Modified's Two Versions
Date math in formula isn't a big date library — it's a few @functions. Add or subtract with @Adjust (seven positions for year/month/day/hour/minute/second, positive or negative); get now with @Now (full timestamp) or @Today (date only); get document times with @Created/@Modified. This piece also flags two traps: @Now re-evaluates every run and hurts efficiency in column/selection formulas, and @Modified (modified initially) vs @ModifiedInThisFile (last modified in this file) differ once you have replicas. Part five of the Formula @function series.
2026.08.29 - @Name Is the Swiss Army Knife for Notes Names: Three Formats, Any Component
In formula you constantly handle Notes names — comparing, displaying, extracting the OU. @Name is the Swiss army knife: [ABBREVIATE]/[CANONICALIZE]/[CN] convert among canonical/abbreviated/common, and [O]/[OU1]/[S] extract any part. Get the current user with @UserName (canonical) or @V3UserName (abbreviated) — but there's a trap: inside a server agent the 'current user' is the signer, and it isn't a security mechanism. Part four of the Formula @function series.
2026.08.28 - String Functions in Formula: @Left/@Right/@Middle, @Word, @ReplaceSubstring
Cutting strings in formula: many people only know @Left(s; 3), the count form — but @Left/@Right/@Middle also take a delimiter string: @Left(email; "@") is everything before the @. @Middle has four signatures, so 'grab what's between X and Y' is one line. This piece covers formula's string tools: @Middle's four forms, @Left/@Right's dual form, @Word to grab the nth piece by separator (-1 for the last, for surnames), and @ReplaceSubstring with parallel lists for multiple replacements. Part three of the Formula @function series.
2026.08.27 - Why You Barely Write Loops to Process a List in Formula
Coming from LotusScript/Java, you'd loop over a list. But formula has almost no loops — because one formula already operates on a whole list at once. This piece treats formula as a functional list language: an operation on a multi-value field runs element-wise (implicit map), @Transform is the explicit map (with @Nothing for filter, a returned list for flatMap), @Explode/@Implode split and join, and @Sort sorts (with [CUSTOMSORT] using $A/$B). What's a ten-line loop elsewhere is often one line of formula. Part two of the Formula @function series.
2026.08.26 - Reading Values Across Views and Databases in Formula: @DbColumn and @DbLookup
To read another view or another database from formula, two functions do ninety percent of the work: @DbColumn grabs a whole column (keyword lists, dropdowns), @DbLookup finds a value by key (resolve a code to a label, pull a related field). This piece covers both signatures, the cache keyword (""/NoCache/ReCache), and the rules you must know — the first column must be sorted, equality-only matching, the 64KB cap, and where they can't be used. Part one of the Formula @function series.
2026.08.25 - @DbLookup and @DbColumn: the Cache Keyword You're Not Passing, and the 64K Wall
You update a keyword document, reload the form, and the dropdown still shows the old value. Or a keyword list quietly stops growing at a few thousand entries. Both are @DbLookup / @DbColumn behaviours hiding in the argument most formulas leave empty: the cache keyword. A field report on the three cache options (default / NoCache / ReCache) and the hard 64KB limit on what these functions can return — with the classic-web cases where each one bites.
2026.08.04 - Domino Web View Paging: Start Isn't a Row Number, It's a Hierarchical Coordinate
"I assumed Start=31 meant the 31st row. Then I was wrong." A debugging field report on the ?OpenView Start parameter in categorized classic views: a plain number jumps to the Nth top-level category, dotted values like 1.1.1.1.6 are hierarchical coordinates, the last segment clamps but middle segments don't, and you can't URL your way to the absolute last page. Plus three practical uses — an in-category serial, @DocNumber("") (with its must-be-alone landmine), and ReadViewEntries breadcrumbs.
2026.07.23 - Why Your Domino View Header Is Forever Off by One Column: Passthrough-HTML Black Magic
Inherit an old classic-web Domino view and you'll often find the column headers sitting one cell to the right of the data — and nobody knows why. A field report on the passthrough-HTML tricks hiding in twenty-year-old view designs: square-bracket HTML in column values and titles, spacer columns, per-row checkboxes, and the real culprit — an intentionally unclosed <input tag that swallows the </td><td> boundary and merges two columns into one cell, shifting every header after it.
2026.07.22