在两个代理之间传递参数

 

Everyone (well, almost everyone) knows that agents can call other agents. A LotusScript agent can call another LotusScript agent using the Run method. You can use the same method to invoke a Java agent, or to invoke a LotusScript agent from a Java agent. When using the Run method, the calling and the called agents will be executed on the same machine (either client or server). An agent running on the client can execute a server-based agent using the RunOnServer method. Again, it doesn"t matter whether the agent is written in Java or LotusScript. Great, right? What else could you want?

Well, release 5.0.2 of Notes/Domino introduces the ability to add parameters to the Run and RunOnServer methods, so that you can pass information between client agents and server agents. In this article, you"ll learn how these methods worked prior to 5.0.2, why the new features solve many problems, and see examples of agents using the new parameters.

The problem: Passing information
Suppose you wanted to pass some information between agents. If you were passing information on the same machine using the Run method, you could use NOTES.INI settings, environment variables, profile documents, or regular documents to store the information you wanted to share. If you were using the RunOnServer method, things get a little more problematic because different clients could invoke the same server-based agent.

You could come up with a scheme by which both the calling agents and the called agents know how to find the same document, and if you wanted to have unique information associated with each user, your scheme would have to key off the user name. But this is not the end of your worries, you also have to worry about the race conditions.

Prior to release 5.0.2 of Notes/Domino, in order to pass information to the agent invoked by the RunOnServer method, you could have used:

• A profile document based on the identity of an EffectiveUser of each calling agent.
• A statically-named regular document, which will be used by all users, where each of the user names would be used as a key.
• A shared document where each user can have his or her own data in the shared document. A separate field is created for each user, with the field name being based on the user"s name. The agent then goes through all the fields on the document, uses the field value as parameters, and sets a new field value to pass back to the invoker. When the invoker gets back control, it retrieves the return value from the same field, and removes the field to mark the job as completed. You can add Authors and Readers fields to the created fields for security.

Each of these approaches potentially has some pitfalls depending on exactly what you are trying to accomplish and how your agent will be used. For example:

• If the authority used in the calling agent is different from the authority used in the called agent, a simple scheme for finding the proper profile document will not work.
• If you are operating in the multiuser dynamic environment where many users can call the same server-based agent, you have to be concerned about replication conflicts if you are using a statically-named document for passing information.
• If the database resides in two locations, the parameter documents could replicate at a wrong time, and contain partial updated data. If the parameter document replicates before the agent clears the value, the agent on the other server will find out-of-date parameter field data when it is invoked, and run incorrectly.

So until now RunOnServer was best suited for invoking standardized processes on demand instead of on a schedule, or in an environment where you don"t need any context.

The solution: Parameters in Run and RunOnServer methods
Release 5.0.2 of Notes/Domino eliminates the problems described above by allowing you to add parameters to both the Run and RunOnServer methods. Both of these methods now accept an optional Note ID parameter. The document identified by the Note ID is accessible from both the calling and the called agents, and can be used to pass parameters between the agents.

The parameter document can be used for both input and output parameters. You must save the document used for parameter passing before it is accessed by another agent. You can delete this document as soon as it is no longer needed. Also, a new agent property called ParameterDocID has been added. This property allows you to retrieve the parameter document ID in the called agent.

The security framework of how Run and RunOnServer works has not changed in this release -- the agents executing on the client run with the authority of the invoker and the agents running on the server run with the authority of the agent signer. For complete information on agent security, see the Agent security at a glance sidebar of the Iris Today article Troubleshooting agents.

The RunOnServer method continues to execute the calling agent on the client and the called agent on the server. So if the calling agent is being invoked by a person other than the signer of the called agent, it is possible for the calling agents and the called agents to run under different authorities. Note that the server-based agent is not executed by the Agent Manager process, but rather in a separate thread created by the client on the server for execution of a given RunOnServer agent.

The Run method is valid both on the client (foreground and background) and on the server (in scheduled, event driven, and Web browser agents). The RunOnServer method is only valid in the agent running on the client (foreground and background).

In Release 5.0.2, if the RunOnServer method is invoked on the server, it will be mapped to the Run method. In prior releases this scenario generated a run time error "RunOnServer must be used with a remote database."

The following table summarizes where Run and RunOnServer are valid: