B_WriteResponse

Note: For backward compatibility with products earlier than extend 10, use the B$ prefix to call the function, instead of B_. From extend 10 onwards, B$ is deprecated.

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
`BIS-Response-Normal`	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. If the XML exchange file has been updated since the last call to `B_ReadRequest`, BIS writes the response into the output and does not redirect to the `OnExit` parameter of the `XMLExchange` tag. If the XML response file has not been updated or has been deleted, and there is an `OnExit` parameter in the `XMLExchange` tag, BIS redirects to the specified page. If the XML response file has not been updated or has been deleted and there is no `OnExit` parameter in the `XMLExchange` tag, BIS writes nothing, but removes the `XMLExchange` tag from the output. 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.
`BIS-Response-ServiceComplete-NoPayload`	Same as `BIS-Response-ServiceComplete` (see above), except the XML exchange response file is always ignored. If there is an `OnExit` parameter in the `XMLExchange` tag, BIS redirects to the specified page. If there is no `OnExit` parameter in the `XMLExchange` tag, BIS renders nothing and removes the `XMLExchange` tag from the output.
`BIS-Response-SessionComplete`	BIS assumes that the both the service complete and no longer complete and no longer needed. If the XML exchange file has been updated since the last call to `B_ReadRequest`, BIS writes the response to the output and does not redirect to the OnExit parameter of the `XMLExchange` tag. If the XML response file has not been updated or has been deleted, and there is an `OnExit` parameter in the `XMLExchange` tag, BIS redirects to the specified page. If the XML response file has not been updated or has been deleted and there is no `OnExit` parameter in the `XMLExchange` tag, BIS writes nothing and removes the `XMLExchange` tag from the output. 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.
`BIS-Response-SessionComplete-NoPayload`	Same as `BIS-Response-SessionComplete` (see above), except the XML exchange response file is always ignored. If there is an `OnExit` parameter in the `XMLExchange` tag, BIS will redirect to the specified page. If there is no `OnExit` parameter in the `XMLExchange` tag, BIS writes nothing and removes the `XMLExchange` tag from the output.
`BIS-Response-RecycleService` `BIS-Response-RecycleService-NoPayload`	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.