One of the topics that seems to keep popping up on the Notes.net Café is passing arguments to agents on the web. Half the postings asking "can you do it?"; the other half asking "how do you do it?". In answer to the first half: yes you can. In answer to the other half: read on...

Passing paramaters to an agent works in exactly the same way as passing parameters to a form or a page: we do it using the Query String portion of the URL. A typical URL looking something like this:

../db.nsf/url?OpenAgent&Name=Jake&Age=26&Country=UK

The code required in the agent to strip these values out of the URL can often become quite complicated and often required hard coding the name of the value that we want to look for. The following code can be re-used in any agent, and simply place all the arguments and their corresponding values in to a nice list. We can then look in this list and retrieve a particular value simply by supplying its name.

The agent starts with the standard declarations:

Dim s As New NotesSession

Dim db As NotesDatabase

Dim doc As NotesDocument

Set db = s.CurrentDatabase

Set doc = s.DocumentContext

Dim AgentArgs List As String

Call ExplodeQueryString (doc.Query_String_Decoded(0)

, AgentArgs)

Forall Args In AgentArgs

 Print "Parameter Key: " + Listtag(Args) + "<br />"

 Print "Parameter Value: " + Args + "<p />"

End Forall

Print "Country Code: " + AgentArgs("country")

Private Sub ExplodeQueryString (QueryString As String,

AgentArgs List As String)

 Dim Args As String 

 Args = RightStr(QueryString, "OpenAgent&")



 Dim ArgsList As Variant 

 ArgsList = Evaluate ({@Explode("} & Args & {"; "&")})



 Dim ArgKey As String

 Dim ArgValue As String



 Forall Arg In ArgsList

  ArgKey = LeftStr(Arg, "=")

  ArgValue = RightStr(Arg, "=")

  AgentArgs(ArgKey) = ArgValue

 End Forall

End Sub

if IsElement( AgentArgs ("ID") ) then

 print "Your ID number is " + AgentArgs ("ID")

else

 print "There is an error in the URL that was used."

end if

Function LeftStr(OrigStr, LeftOf ) As String

 Dim Pos As Integer

 Dim OrigStrLen As Integer

 Pos = Instr( Lcase(OrigStr), Lcase(LeftOf) )

 OrigStrLen = Len(OrigStr)

 If pos>0 Then

  LeftStr = Left( OrigStr, (Pos-1))

 Else

  LeftStr = OrigStr

 End If

End Function



Function RightStr(OrigStr, RightOf ) As String

 Dim Pos As Integer

 Dim OrigStrLen As Integer

 Dim RightOfLen As Integer

 Pos = Instr( Lcase(OrigStr), Lcase(RightOf) )

 OrigStrLen = Len(OrigStr)

 RightOfLen = Len(RightOf)

 If Pos>0 Then

  RightStr = Right( OrigStr, OrigStrLen -

(RightOfLen+Pos-1))

 Else

  RightStr = OrigStr

 End If

End Function