I was working on a project recently with an agent I knew would time out. Instead of having the agent just fail, I wanted to stop the agent gracefully and log why it was stopping. So I set the agent to keep track of how long it was running and at some point after 29 minutes (there's processing going on, it could be 29 minutes and 0 seconds, it could be 29 minutes and 50 seconds depending on how things work out) the agent would log that it's stopping before timing out.

The easiest way to keep track of how long an agent has been running is with 2 NotesDateTime objects. Set one at the start of the agent, set the other later on, then compare the differences. The comparison is in seconds.

   Dim agentStart As NotesDateTime
   Dim rightNow As NotesDateTime
   Dim elapsedTime As Long

Initialize the values at the start of the agent:

   Set agentStart = New NotesDateTime(Now)
   Set rightNow = New NotesDateTime(Now)

Then, later on, change the value of "rightNow" and do the comparison:

      Call rightNow.Setnow()
      elapsedTime = rightNow.Timedifference(agentStart)
      If elapsedTime > (MAX_MINUTES_TO_RUN*60) Then
         Call agentLog.Logaction("Agent has been running for " & ConvertSecondsToHHMMSS(elapsedTime) & ". Stopping due to maximum elapsed time.")
         Set doc = Nothing
      End If
   Wend

MAX_MINUTES_TO_RUN is a global constant set to 29 because in the server document agents are allowed to run for 30 minutes. The logging goes to a standard NotesLog object, but that's easy enough to change to OpenLog or whatever your preference is. And setting the NotesDocument variable doc to Nothing gets the code out of a While loop and exits gracefully.

What about that "ConvertSecondsToHHMMSS" function? That function takes a number of seconds as a parameter and converts that value to hours, minutes, and seconds. Note that it doesn't handle days - I'm assuming the number of seconds is less than 24 hours.

Function ConvertSecondsToHHMMSS(numSeconds As Long) As String
   On Error GoTo BubbleError
   ' Convert a number of seconds to HH:MM:SS (hours minutes seconds)
   Dim hours As Integer
   Dim minutes As Integer
   Dim seconds As Integer
   Dim retVal As String

   hours = Int(numSeconds / 3600)
   minutes = Int((numSeconds-(hours*3600))/60)
   seconds = numSeconds - (hours*3600) - (minutes*60)

   retVal = CStr(hours) & ":"
   If minutes < 10 Then retVal = retVal & "0" & CStr(minutes) Else retVal = retVal & CStr(minutes)
   If seconds < 10 Then retVal = retVal & ":0" & CStr(seconds) Else retVal = retVal & ":" & CStr(seconds)

   ConvertSecondsToHHMMSS = retVal

   Exit Function
BubbleError:
   Error Err, Error$ & Chr$(10) & "in function " & GetThreadInfo(1) & ", line " & CStr(Erl)
End Function

The code is pretty easy to follow. Convert the seconds to hours, minutes, and seconds. Then put those all together with leading zeros as necessary. Hours will always be present (even if it's zero) but will only be a single character long. Minutes and seconds will both be 2 characters long (leading zero if needed).