In a project a while back, there was an application that had a lot of new documents created all day. The number of documents kept increasing and increasing, so we decided to simply purge documents after 14 days. But that ended up not being satisfactory for users who wanted to create reports on the old data. Instead of taking up server space (which cost money from the hosting company), we decided to leave it up to the individual users to copy documents to their local machines before they were purged from the server. But this meant setting up a scheduled agent on the user's workstation, which meant that the user needed to have "Enable Scheduled Local Agents" enabled on their workstation (figure 1).

We needed a way to check to see if this setting was enabled, and tell the user how to enable it. (Since this setting takes effect the next time Notes starts, it was much easier using this method then setting it ourselves and telling the user to restart Notes).

This setting, along with others, is stored in the "Preferences" INI variable. You can access the current value through the GetEnvironmentString method of the NotesSession class. It is not an environment variable prefixed with a dollar sign, so you must specify True as the second parameter to the method. Here is some example code that will show you what your current value is:
Dim s As New NotesSession
Dim preferences As Long
preferences = Val(s.GetEnvironmentString("Preferences", True))
Msgbox Cstr(preferences)

You will see a long number (10 digits or so, possibly negative). So what does this all mean? Well, there are a lot of preferences stored here. To Notes, this number is really a very long binary number. If a certain bit is 0, that setting is disabled. If it's 1, that setting is enabled. So it's just a matter of finding out what bit to check and then checking if it's enabled or disabled.

Finding Out The Bit

To find out the bit that controls the setting, run the code above and write down the number you are shown. Then go enable or disable the setting, restart Notes, and run the code again. Subtract the two numbers and you'll end up with some number that is a power of 2. In the case of the "Enable Scheduled Local Agents" setting, the number is 134217728 (134 million, 217 thousand, 728), which is 2^27 power, which is the 27th bit.

Once you know the bit to enable, convert that value to hex (for preferences, the value is "8000000" ("8" followed by 6 zeros). In binary, that will be "1" followed by 26 zeros since it's the 27th bit. Since each hex digit represents a group of 4 binary digits, there are 6 groups of 4 zeros (giving the 6 zeros at the end of the hex number), and "100" (what's left at the start) translates to a hex "8".

After you know the hex value to compare, you can expand your code to check to see if that bit is enabled or disabled:
Dim s As New NotesSession
Dim preferences As Long
Dim compare As Long
Dim msg As String
preferences = Val(s.GetEnvironmentString("Preferences", True))
compare = &H8000000 ' Put in your hex value here after the "&H"
If (Not preferences) And compare Then
    msg = "You do not have local scheduled agents enabled." & Chr$(10) & Chr$(10)
    msg = msg & "Please enable local scheduled agents (through File | Preferences | User Preferences)"
    msg = msg & " and restart Notes."
    Msgbox msg, 16, "Local Agents Not Enabled"
    Exit Sub
End If
' Continue with your code... enable the scheduled agent or whatever

Obviously, you'll need to change the instructional message depending on the setting, but these are the steps to follow for any of those settings. If you don't understand the Boolean logic being used, we are checking for a bit-by-bit match on all bits from "compare" that are "1". We are checking the corresponding bit in "preferences" to be DISABLED (because NOT is used). There is only one bit enabled in "compare", so that is the only bit checked in "preferences". If that bit is disabled, the message is shown and the code exits.