This function call retrieves the current BIS request for processing by the service program. The syntax of this function call is:
Call "B$ReadRequest" [using TimeoutInSeconds] giving BIS-Status.
When this function is called, execution of the service program is suspended until one of the following events occurs:
| Event | Action |
|---|---|
| The BIS Request Handler renders an XMLExchange tag for the current session | This tag causes the current request data to be encoded into XML and placed into the file specified by the BIS_FILENAME environment variable. |
|
The BIS Request Handler renders a StopService or SessionComplete tag for the current session |
This indicates that the service is no longer required. The service program should terminate and is granted [ServiceTimeout] seconds to do so. |
| The optional TimeoutInSeconds parameter expires | This timeout allows the BIS service program to regain control and perform some work. When complete, the program should call B$ReadRequest again. |
| The InactivityTimeout period expires | This indicates that the end user has abandoned the session. The service program should terminate and is granted 30 seconds to do so. |
The most common result codes are as follows (see BIS Return Codes for a complete table):
| BIS-Status Code | Event Description |
|---|---|
| BIS-Success | A valid request was received. |
| BIS-Warn-RequestTimeExpired | The TimeoutInSeconds parameter was specified and no request was received before the time elapsed. |
| BIS-Warn-RequestOutstanding |
A request is outstanding. The service program must write a response before another request can be received. This code is only returned by BIS/Apache; BIS/IIS recreates the exchange file and returns BIS_Success each time that B$ReadRequest is called for the same request. |
| BIS-Fail-SessionAbandoned | Service termination is being requested because the BIS session inactivity time has elapsed without a request. |
| BIS-Fail-SessionComplete | Service termination is being requested because a StopService tag was rendered. |
| BIS-Fail-ServiceComplete | Service termination is being requested because a SessionComplete tag was rendered. |
(These values are defined in file bisdef.cpy). Other codes may also be returned; see BIS Return Codes
When execution resumes and the result code is BIS-Success, the file specified by the BIS_FILENAME environment variable contains the request in XML format. The exact format of the request is described in Appendix B, XML Exchange Request File Format.