Agents are a special category of system service, and are used most often in communications software. Like filters, agents intercept requests before they arrive at their destination service. However, while a filter modifies a request and forwards it to a service on the same processor, an agent acts as a means to transport requests between processors.
Writing Request-Based System Services 8-25
Two types of agent exist; the client agent and the server agent. The client agent resides on the same processor as the client application. The server agent resides on the same processor as the system service the client needs.
Figure 8-1 shows the model of interaction between a client and a server through agents.
Client's Processor
z
Service's Processor
Figure 8-1. The Role of Agents in Request Passing
Role of the Client Agent
When the client agent receives a connection-opening or a connectionless request, it must determine which processor hosts the requested system service. It does this by parsing the data field pointed to by one of the request pbcb pairs in the request block. For example, it might parse the pbcb that identifies the file specification on a open file request. The request definition tables in the operating system identify which pbcb should be used.
The response to a connection-opening request always contains a handle from the remote service. The agent must save this handle for its own use, and allocate anew, local handle, for use by the client application. It then returns this new handle to the client.
8-26 eTaS/Open Programming Practices and Standards - Part I
When the client agent receives a subsequent connection-oriented request from the client, such as a read on a previously opened file, that request contains the local handle. The agent must then look up the handle it received from the remote service, and forward the request block to the service agent at the remote processor.
Finally, when it receives a close request, it must forward that request to the remote service. Then, after it receives a response from the remote service, it deallocates the remote connection handle, and responds to the client. This frees both the local and the remote connection handle for use on a subsequent connection.
In a network environment, the client agent must also track which remote processors a client has communicated with, and forward system requests for the client to all those processors. This allows the remote processors to deallocate resources when the client terminates. In addition, when it receives a response from a remote processor to a termination request, the agent must deallocate the handles for any resources on the remote processor that are owned by the terminating client.
Role of the Server Agent
The server agent acts on behalf of a remote client, by submitting the client's requests to the local operating system. To perform this role, the server agent must allocate local memory to store a copy of the client's request block, and any associated data.
When the remote client issues a request, the service agent receives the request block and request data from the remote client agent. It can then forward the request block to the local destination system service. When the server agent receives a response from the local system service, it sends the request block and the response data back to the client agent.
The service agent must also ensure that all user numbers are unique on its local processor. If a remote client has the same user number as a local partition, the service agent must map the client's user number to an unused local user number.
Writing Request-Based System'Services 8-27
Request-Passing Guidelines for Agents
The transfer of requests between processors is optimized to minimize the amount of data that must actually be transferred. When a request is sent from a client agent to a server agent, the lower level network interfaces should send only the request block and the data pointed to by the request pbcb pairs.
When a response is sent from a server agent to a client agent, the lower level network interfaces needs to send only the request block and the data pointed to by the response pbcb pairs.
Implicit in these definitions is the fact that the contents of a request block may change as it passes through a network, and still remain valid.
Therefore, agents should not count on receiving the same values in a request block that the client originally put there. Agents can, however, count on receiving consistent information in a series of requests. For example, all requests an agent receives for a given connection will contain the same connection handle, but the connection handle seen by an agent may be different from the one seen by the client application.
Piecemealing of Very Large Request Blocks
As described above, the service agent must provide local storage for the request blocks, request data, and response data. Therefore, it is possible for a request to be too large to fit in the service agent's buffers. This occurs most often for disk read and write requests, where using large blocks of data tends to optimize disk access time.
When a request is too large for its server agent to handle, the client agent should use piecemealing. Piecemealing consists of breaking a large request into several smaller requests, each of which is sent to the server agent individually.
In order to support piecemealing, a request must follow the format shown in Table 8-5. The request always has two pbcbs. The first one may be either a request or a response, depending on whether the operation performs a read or a write. The second is always a response pbcb. For piecemealing to occur, the request must also be defined as a piecemealable request in its :NetRouting: field in the request definition file.
8-28 eTOS/Open Programming Practices and Standards - Part I
Table 8-5. A Piecemealable Request Block
Size
Offset Field (Bytes) Contents
0 sCntlinfo 6
RtCode 0
2 nReqPbCb o or 1
3 nRespPbCb 1 or 2
4 userNum 2 User Number
6 exchResp 2 Response Exchange
8 ercRet 2 Status Code Returned
10 rqCode 2 Request Code
12 fh 2 File Handle
14 If a 4 Logical File Address
18 pbData 4 Data Buffer
22 cbData 2
24 pbCountRet 4 Returned Byte Count
28 cbCountRet 2 2
When the client agent detects a request that is too big for the service agent, and if the request can be piecemealed, it generates a series of requests small enough to fit in the service agent's buffer.
In each request, the client sends a piece of the original data, and changes the logical file address to indicate the position of that piece in the original data. As each response returns, the client agent adds the count of bytes processed to a running total.
Thus, after the server agent has responded to all the piecemealed requests, the client agent has a count of the total number of bytes processed.
If an error occurs in the processing of one piece of a piecemealed request block, the client application receives the error code. If more than one piece of the original request encounters an error, the client application
Writing Request-Based System Services 8-29
receives only the numerically largest error code. Because the client only issued one request, it can only receive one error code.