B$WriteResponse

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.

  1. If there is an OnExit parameter in the XMLExchange tag, BIS will redirect to the specified page.
  2. 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.