Related Topics
Other Library Functions

wsb.dispatch-request

function

Library: Web Services Broker (OMWSB)
Import : omwsb.xmd

Declaration 
export external function dispatch-request
                            value request request
  using                     value server  server 
  to                        value string  program
  using-unique-directory    value switch  unique-dir optional initial {false}
  retain                    value switch  retain     optional initial {false}
  args                  read-only stream  args       optional

Argument definitions

request
A wsb.request OMX variable that was returned from a call to wsb.wait-for-request
server
A wsb.server OMX variable that was returned from a call to wsb.create-server, and the server from which the request was received
program
The path of a compiled OmniMark program which will service the specified request
unique-dir
When true, a unique directory will be created for this service, which it can then retrieve using the read-service-arguments function.
retain
When both this parameter and unique-dirs are true, then the created unique directory will nto be deleted when the service exits.
args
Takes a keyed shelf which the service instance can then retrieve using the read-service-arguments function.


Purpose

The dispatch-request function call is used by the server program to transfer the processing of a request to a service program. This function is typically used when the server is handling an unknown request and wants the processing to be done in a separate thread as opposed to processing the request itself. The program must be a WSB service program just like the service programs that are added via the add-service call.

Note that it is much more efficient to have a registered service handle a particular request than to manually recognize and dispatch them in the server loop.

If unique-dir is true, the WSB server will create a unique directory for this instance of this service prior to the instance starting. Then, when the instance later shuts down, the directory is deleted. This feature is useful for situations where services need a work area on the filesystem where they won't clash with other currently running services.

The same parameter is available on the wsb.create-server function if this functionality is required by all services. In general, this feature should only be enabled for those services which require it, as it does incur a small performance penalty during instance startup.

By default, unique directories will be created in the system temporary directory (often /tmp/ or C:\temp). However, a different directory can be specified as a parameter to the wsb.create-server function.

Specifying the retain parameter is primarily useful for debugging a service which creates files and/or directories in its unique directory. This parameter should not be set to true in any other circumstance, as it leaves all the unique directories on the filesystem when the service exits.

When args is specified, a copy of the passed shelf is made and stored. The service instance can then retrieve a copy of that shelf using the read-service-arguments function.

Related Topics
Other Library Functions