Passing arguments to a LotusScript agent

Jake Howlett, 21 November 2000

Category: Agents; Keywords: URL Arguments Parse Query String

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

Followed by declaring the list variable that will hold all the arguments and their values:

Dim AgentArgs List As String

and a call to the subroutine that does all the work (code appears further down the page):

Call ExplodeQueryString (doc.Query_String_Decoded(0)

, AgentArgs)

This list would normally be used to let the agent go and retrieve the required information, but, for the sake of a demo, lets loop through all the parameters and send their key/value pairs back to the browser:

Forall Args In AgentArgs

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

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

End Forall

This method of looping through ALL the arguments may not be necessary if you already know the name of the parameter's key. For example, if a key had the name "Country", you could get to its value like this:

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

The ExplodeQueryString sub-routine:

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

In order to reference a member of the list explicitly, like we did above, it is wise to check that it exists first. If you try to access a list item that does not exist the script will error. Use the IsElement method to help avoid errors:

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

Overall, not a particularly useful example, I know, but I'll leave it to you as to how you wish to implement it.....

The LeftStr and RightStr functions

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