Option Declare

Sub Initialize
	' using an agent's title, get agent as document via its ID.
	Dim s As New NotesSession
	Dim db As NotesDatabase						' current database
	Dim curserver As String							' this/current server of db
	Dim nDb As NotesDatabase						' an application containing the agent
	Dim agentid As String							' source noteid of agent, needed to get as document and copy
	Dim agentnm As String							' name of the forwarding agent ($Title), used to check for existence
	Dim agDoc As NotesDocument						' agent as document
	
	On Error Goto ErrorHandler
	
	' setup environment
	agentnm = "MyAgentName"
	agentid = ""									' retrieved by title via cycling through the agents within this application
	Set db = s.CurrentDatabase
	curserver = db.Server
	Set nDb = LSGetDatabase(s, curserver, "mydb.nsf")
	If (nDb Is Nothing) Then
		' give up
		Print "Cannot get mydb.nsf on this server. Aborted."
		Exit Sub
	End If
	' get the note id for agent
	agentid = GetAgentNoteID(db, agentnm)
	If (agentid = "") Then
		Print "Cannot get agent id using title: " & agentnm & ". Aborted."
		Exit Sub
	End If
	' get the agent as a document
	Set agDoc = db.GetDocumentByID(agentid)
	If (agDoc Is Nothing) Then
		Print "Cannot get agent id using id: " & agentid & ". Aborted."
		Exit Sub
	End If
	
	' …. do whatever …..

	' done
	Print "Done running agent."
	
	Exit Sub
ErrorHandler:
	Print "Unexpected Error: " & Cstr(Err) & " " & Error$ & ", on line: " & Cstr(Erl)
End Sub

Function GetAgentNoteID(db As NotesDatabase, agtitle As String) As String
	' get's all agents in database and returns agent ID
	' useful to get agent as a document
	Dim s As New NotesSession
	Dim nnC As NotesNoteCollection				' collection of views
	Dim nid As String							' note id of each note in nnc (view)
	Dim doc As NotesDocument					' getting agent design notes by id
	Dim dItem As NotesItem						' title of view note of doc
	Dim dtitle As String							' alias/title of agent
	
	On Error Goto FErrorHandler
	
	GetAgentNoteID = ""
	' do tests
	If (db Is Nothing) Then
		Exit Function
	End If
	If (agtitle = "") Then
		Exit Function
	End If
	
	' create empty collection object
	Set nnC = db.CreateNoteCollection(False)				' start empty
	nnC.SelectAgents = True
	Call nnC.BuildCollection							' contains all agents in db, we need to loop them
	nid = nnC.GetFirstNoteId()
	While Not (nid = "")
		' get the "document" for the agent and then its title
		Print nid
		Set doc = db.GetDocumentByID(nid)
		If (doc Is Nothing) Then
			Print "No doc for id: " & nid "."
		Else
			Set dItem = doc.GetFirstItem("$TITLE")
			If (dItem Is Nothing) Then
				Print  "Skipped: " & nid & ". No title."
			Else
				' get the view title/alias so we can get the view
				dtitle = dItem.Text
				If (Strcompare(dtitle, agtitle, 5) =0) Then
					' exact match, have agent, return id and stop looping
					GetAgentNoteID = nid
					Set dItem = Nothing
					Set doc = Nothing
					Goto FExit
				End If
			End If
		End If
		
		' get next id
		dtitle = ""
		Set dItem = Nothing
		Set doc = Nothing
		nid = nnC.GetNextNoteId(nid)
	Wend
	
	' done return current value
FExit:
	Exit Function
FErrorHandler:
	Print "(GetAgentNoteID) Unexpected Error: " & Cstr(Err) & " " & Error$ & ", on line: " & Cstr(Erl) & "."
	GetAgentNoteID = ""
	Resume FExit
End Function

Function LSGetDatabase(s As NotesSession, dbserver As String, dbfile As String) As NotesDatabase
	' gets a database, use function to isolate the get, opening into one neat line of code
	Dim aDb As NotesDatabase					' database to get
	
	On Error Goto FErrorHandler
	
	' start with LSGetDatabase = Nothing
	Set LSGetDatabase = Nothing
	
	' gets database
	Set aDb = s.GetDatabase(dbserver, dbfile, False)
	If (aDb Is Nothing) Then
		' give up
		Print "Cannot get names.nsf on this server. Aborted."
		Exit Function
	End If
	If Not (aDb.IsOpen) Then
		' open, usually not open because of ACL issue, this will likely cause error and we'll be aborted
		Call aDb.Open(dbserver, dbfile)
		If Not (aDb.IsOpen) Then
			' give up
			Print "Cannot open, " & dbfile & ", on server, " & dbserver & ". Aborted."
			Set LSGetDatabase = Nothing
			Exit Function
		End If
	End If
	' done.
	Set LSGetDatabase = aDb
FExit:
	Exit Function
FErrorHandler:
	Print "(LSGetDatabase) Error: " & Cstr(Err) & " " & Error$ & ", on line: " & Cstr(Erl) & ". Returning nothing."
	Set LSGetDatabase = Nothing
	Resume FExit
End Function