LDD Today

Ask Professor INI
Agent variables
This month, "Ask Professor INI" marks its second anniversary. In honor of the occasion, this column returns to its roots and answers questions sent in by readers. In particular, we'll be responding to queries concerning agent-related variables—a topic so important and obvious, you may well wonder why it took Professor INI two whole years to finally get around to it!

Q. Where can I find the complete list of agent-related Notes.ini variables?
There are a good number of agent-related Notes.ini settings out there. Some are documented in the Domino Administration Help, for example the AMgr family of settings that help control Agent Manager. Others are not (for instance Debug_AMgr, mentioned later in this column). Professor INI advises you to stick with the documented variables if at all possible, and only venture into undocumented territory if you find this information in an LDD Today article or other IBM-sponsored site (or better yet, you're working under the guidance of Lotus Support). As always, Professor INI will be on the lookout for agent-related variables that may not be documented but are still supported and helpful if used carefully.

Q. What is the setting JavaUserClasses used for?
JavaUserClasses allows code-sharing across agents and applets. Its syntax is JavaUserClasses = list where list identifies directories, JAR files, and/or ZIP files to be added to the Java Virtual Machine's internal classpath. When you set this variables, classes can be found via the system loader (rather than via attachment to the agent or applet). Normally JavaUserClasses applies to servers. However, it does have an undocumented use on the Notes client as wellm involving the use of Swing (Java Foundation Classes) in Notes. (The Swing toolkit, available from Sun, is a UI component library implemented in Java. Its components comply with the JavaBeans specification.) To use Swing in Notes, you must edit Notes.ini and add the line JavaUserClasses=<pathname>\swingall.jar, where <pathname> represents the location of swingall.jar.

Q. I'm looking for a parameter in the Notes.ini file that allows a scheduled agent to run more frequently than every five minutes. Any ideas?
Professor INI knows of no such variable. As you know, when creating a scheduled agent, you can specify that it runs multiple times each day at regular intervals. The shortest interval allowed is five minutes. (If this interval were much shorter, it could impact server performance.) You can of course have the Agent Manager look at its schedule queue as often as every minute through the variable AMgr_SchedulingInterval.

Q. In an earlier Professor INI column, you mentioned DominoAsynchronizeAgents. Isn't the Run web agents concurrently field in the Server document the same thing as setting DominoAsynchronizeAgents?
You are correct. The Run web agents concurrently option was introduced in R5. However, R5 still supports the variable DominoAsynchronizeAgents for backward-compatibility. In R5, you can overwrite the Run web agents concurrently setting through DominoAsynchronousAgents. Note, however, that this variable is no longer documented or supported in Domino 6.

Q. How can I turn off logging of agent events in the server log?
The variable Log_AgentManager controls the level at which agent events are logged. For example, Log_AgentManager results in no agent execution events being logged. Other possible values are 1 (for logging events that are at least partially successful) and 2 (for logging only completely successful events). There is no default value nor is there a UI equivalent for Log_AgentManager.

As an aside, Log_AgentManager can be an important tool for troubleshooting agents, especially when used in conjunction with Debug_AMgr and Debug_Outfile. Debug_Amgr (an undocumented variable) turns on Agent Manager debugging, which can be useful in diagnosing problems with scheduled agents (both on the Domino server as well as the Notes client). The variable explicitly sets the level at which debugging information is recorded. For example, Debug_AMgr=m outputs agent memory warnings; Debug_AMgr=p reports agent performance statistics. There are nine possible values for Debug_AMgr, including Debug_AMgr=* (which combines the output of all eight of the other settings). You can use these settings singly or in combination. For more information on Debug_AMgr settings and how to use them, see the LDD Today article "Troubleshooting agents."

Log_AgentManager, as we already mentioned, provides a subset of Debug_AMgr information. However, Log_AgentManager has a smaller impact on performance.

Finally you can use Debug_Outfile to record log messages (including, but not limited to, agent events) to a text file. Debug_Outfile is documented in the Domino Administrator Help.

Q. Which settings affect the timing of when my agents will run?
Sometimes these questions are almost suspiciously easy. Julie Kadashevich has written the definitive article on minimizing time delays from agents and the Agent Manager. In her LDD Today article "Minimizing delays in the Agent Manager, Julie mentions the following Notes.ini variables that affect when an agent runs. (Note that all of these settings are documented and supported.)

Notes.ini settingDescription
AMgr_DocUpdateAgentMinIntervalSpecifies the minimum elapsed time (in minutes) between execution of the same document update-triggered agent. The default is 30 minutes.
AMgr_DocUpdateEventDelaySets a delay of execution (in minutes) that the Agent Manager includes in the schedule for a document update-triggered agent after a document update event. The default is five minutes.
AMgr_NewMailAgentMinIntervalSpecifies the minimum elapsed time (in minutes) between execution of the same new mail-triggered agent. The default value is zero.
AMgr_NewMailEventDelaySets a delay of execution (in minutes) that the Agent Manager includes in the schedule for a new mail-triggered agent after a new mail message is delivered. The default is one minute.
AMgr_SchedulingIntervalSpecifies the delay (in minutes) between runnings of the Agent Manager's scheduler. This can be one to 60 minutes; the default value is one minute.
AMgr_UntriggeredMailInterval Sets the delay (in minutes) between runnings of the Agent Manager's check for untriggered mail. Values can be one minute to 1440 minutes (one entire day). The default is 60 minutes.

Q. My mail agents don't run. Can I use Notes.ini to fix this?
OK, so no one really asked us this question. But it's such a useful topic, Professor INI decided to briefly mention it anyway. Agents set to execute after new mail has arrived are designed to run on the home mail server of the signer. However, these agents may end up on some other server (for example, through replication). When you try to execute the mail agent in this case, it checks to see whether the current server is your home server, discovers it isn't, and stops running. You can suppress the check for the home mail server by adding AMgr_DisableMailLookup =1 to the server's Notes.ini file (but be aware this can have side effects, as explained in the LDD Today article "Troubleshooting agents").


Do you have a Notes.ini question? Send it in to Professor INI. We'll answer as many questions as we can in future "Ask Professor INI" columns. Keep in mind, however, that we may not be able to answer every question, nor can we quickly respond to requests that require immediate attention. If you need an immediate response to a question, we recommend you post it in the Notes/Domino 6 Forum or the Notes/Domino 4 and 5 Forum where someone from the general Notes community might be able to help, or contact Lotus Support Services.