This function call transmits a response to the BIS Request Handler to be inserted into the output stream, replacing the XMLExchange tag in the output stream. The response must be written into the request file (specified by the BIS_FILENAME environment variable) before B_WriteResponse is called unless session or service termination is being requested-in this case, the response is optional (see below).
The response file typically contains an requested HTML or XML that is inserted into the .srf file. It may also contain a SOAP result or anything else that is meaningful to the client program that issued the request.
The syntax of this function call is:
Call "B_WriteResponse" [using ProgramDisposition] giving BIS-Status.
If this is the final call to B_WriteResponse by this service, the optional ProgramDisposition parameter may be used to indicate that the service program is finished, if the session should be destroyed, and if there is a payload that should be rendered into the response. Here are the values:
78 BIS-Response-Normal Value 0. *> Default normal response 78 BIS-Response-ServiceComplete Value 1. *> End program only 78 BIS-Response-SessionComplete Value 2. *> End program and session *78*BIS-Response-RecycleService Value 3. *> RESERVED FOR FUTURE USE
The ProgramDisposition codes descriptions are as follows:
|BIS-Status Code||Event Description|
The default is that BIS makes no assumptions about what the service program will do next. However, the service program is granted only 30 seconds to exit or to read the next request.
This response always requires a valid XML exchange file. If the file has not been updated with a response, or has been deleted, this function will return BIS-Fail-FileNotChanged.
|BIS-Response-ServiceComplete||BIS assumes that the service has completed processing and longer needs to interact with the session.
In all cases, the service program disconnects from the session and has 30 seconds to run to completion in the background. If the service program subsequently calls B_ReadRequest it receives a BIS-Fail-ServiceComplete error status.
The session is not destroyed by this response, and if a StartService tag is executed before the session expires, the new service program runs under the current session. The session can be terminated if the page requested by OnExit is a stencil and contains a SessionComplete tag.
This disposition option is logically the same as processing a StopService tag in the requesting stencil or in the XML response.
Same as BIS-Response-ServiceComplete (see above), except the XML exchange response file is always ignored.
BIS assumes that the both the service complete and no longer complete and no longer needed.
In all cases, the service program and the session are both disconnected (becoming inaccessible to subsequent requests) and the service program disconnects from the session and has 30 seconds to run to completion in the background.. If the service program subsequently calls B_ReadRequest it receives a BIS-Fail-SessionComplete error status.
Once the service program terminates, the session is destroyed. If another request is received, a new session is created to process the request.
This is logically the same as processing a SessionComplete tag in the requesting stencil or in the XML response.
Same as BIS-Response-SessionComplete (see above), except the XML exchange response file is always ignored.
|Reserved for future use.|
The BIS-Status result field and the result codes are defined in bisdef.cpy. Here are the most common return codes:
|BIS-Status Code||Event Description|
|BIS-Success||The BIS Request Handler accepted the response. This does not mean that it was delivered to the user agent. However, the service program should presume success and resume processing.|
|BIS-Warn-ResponseUnexpected||There is no pending request to respond to.|
|BIS-Fail-FileNotChanged||The XML exchange file was not written and still contains the request. Note that this code is only returned for the BIS-Response-Normal disposition code, as the exchange file need not be updated if the service or session are terminating.|