Easily Enable and Disable Background Agents Programmatically with this LotusScript Function

Kenneth Haggman


November, 2008

Make upgrading your Notes database code easier by using the LotusScript function Kenneth provides, which allows you to programmatically enable and disable background agents. This function takes care of working with the Lotus C API so you don’t have to. Learn about the LotusScript function from a demonstration database, then learn how to use the function in your own update agent code.

Picture this scenario: You’re a developer who needs to implement some major changes to a database, and your upgrade code requires hours to process. Although you can’t allow users to run agents that could disrupt your upgrade, you want to provide users with continuous access to the database for certain tasks, such as viewing or editing documents from the Notes client.
In this scenario, to ensure that absolutely no schedule or background agents execute while you’re updating a database’s code, you must temporarily disable them during the upgrade. While disabling scheduled agents programmatically with LotusScript isn’t a problem, disabling background agents programmatically is challenging. There is no LotusScript, JavaScript, or formula language function to set the Notes and Domino (release 6 onward) database property "Disable background agents for this database" (Figure 1). You must use the Lotus C Application Programming Interface (API) to access and set this property. There is, however, no need to play around with the C language; you can access the necessary C API functions directly with LotusScript, using a LotusScript function I created for just this purpose. I’ve been using this function for some time now with no problems.
The custom LotusScript function, called "setDisableAgentFlag," does all the work of utilizing the Lotus C API so you can disable background agents in Notes 6+ databases in a snap. The Lotus C API is a part of all Notes 6+ clients, so you don’t need to install it for the solution to work. I provide this function as part of the LotusScript library called “(LIB: SetDisableAgents)” in the demonstration database that you can download from the link above, ChangeDbPropertywithCAPI.nsf.
After demonstrating the setDisableAgentFlag function at work, I tell you how to use it in your own applications. For those who want to know the inner mechanics of working with the Lotus C API, I go on to discuss the library code. (For some background on Lotus C API, refer to articles mentioned in the "Lotus C API" sidebar.)[sidebar reference]

Would you like to see the full version of this article?

If you are an electronic license holder to THE VIEW, please log in to view this article.

If you would like information about becoming an electronic license holder — and having 24/7 unrestricted access to all articles and content in THE VIEW Online Knowledgebase — click here to see the available subscription options.

Or call 1-781-751-8813 to speak directly with a subscription and licensing specialist about customized access for you and your team.