Back to Contents

The WebServiceEngine class

Summary:

See also: The Genero Web Services COM Library

Syntax

The WebServiceEngine class provides an interface to manage the Web Services Engine. This class does not have to be instantiated.

Note that status is set to zero after a successful method call.

Syntax:

com.WebServiceEngine

Methods:

Class Methods
Name Description
com.WebServiceEngine.RegisterService(
  ws com.WebService )		 Registers a WebService to the DVM, where ws is the WebService to be registered.

Throws an exception in case of errors, and updates status with an error code.

com.WebServiceEngine.Start() Starts all registered Web Services.

Throws an exception if the services cannot be started.
com.WebServiceEngine.ProcessServices(
  timeout INTEGER )
  RETURNING status 		Specifies the wait period for an HTTP input request, to process an operation of one of the registered Web Services. timeout is the time in seconds to wait for an incoming request before returning; the value -1 specifies an infinite waiting time. Returns a value indicating the status.
com.WebServiceEngine.getHTTPServiceRequest(
  timeout INTEGER )
  RETURNING com.HTTPServiceRequest 		Returns a HTTPServiceRequest object to handle an incoming HTTP request, or null if there was none during the given period of time. timeout is the time in seconds to wait for an incoming request, and -1 means infinite wait. Any new call to this function will raise an error until the previous HTTP request was handled by sending a response back to the client, or destroyed.

Throws an exception in case of errors, and updates status with an error code.

com.WebServiceEngine.HandleRequest(
  timeout INTEGER,
  status INTEGER )
  RETURNING com.HTTPServiceRequest 		Processes any HTTP input request in the given period of time.
  • If there is no request in the given period of time, or if there is an error, the status code is updated by reference, and a NULL object is returned.
  • If the request is intended to a registered web service, it is processed automatically. The status code is updated by reference and a NULL object is returned.
  • If the request isn't dedicated to a registered web service, a status code of value 1 is returned by reference, and a valid instance of an HTTPServiceRequest object, immediately usable to handle the incoming request, is returned.
Throws an exception in case of errors, and updates status with an error code.
com.WebServiceEngine.SetFaultCode(
  code STRING,
  codeNS STRING ) 		Defines a user SOAP Fault code to be returned to the client, where code is the mandatory SOAP Fault code and codeNS is the mandatory Code namespace. This function has an effect only if called inside a WebService operation.
com.WebServiceEngine.SetFaultString(
  str STRING )		 Defines a user SOAP Fault description to be returned to the client, where str is the description string. This function has an effect only if called inside a WebService operation.
com.WebServiceEngine.SetFaultDetail(
  fault VARIABLE ) 		Defines the published SOAP Fault to be returned to the client when operation has finished, where fault is one of the published variables defined as Fault for that operation. This function has an effect only if called inside a WebService operation. An error is throw if fault isn't a valid SOAP fault.
com.WebServiceEngine.SetOption(
  flag STRING,
  value STRING ) 		Sets an option flag to change the global behavior of the Web Services engine, where flag is the option flag and value is the value of the flag. See Global option flags.

Throws an exception in case of errors, and updates status with an error code.

com.WebServiceEngine.GetOption(
  flag STRING )
  RETURNING value 		Gets an option flag value of the Web Services engine, where flag is the option flag and value is the value of the flag. See Global option flags.

Throws an exception in case of errors, and updates status with an error code.

Back to the top

Usage

A human-readable description of the error codes for RegisterService, ProcessServices and HandleRequest  is available in the SQLCA.SQLERRM structure.

ProcessServices and HandleRequest return a status value with the following meaning:

      1 : A valid instance of an HTTPServiceRequest object has been returned (only for HandleRequest)
      0 : A request has been processed successfully
    -1 : Time out reached
    -2 : Disconnected from application server
    -3 : Lost connection with the client
    -4 : Server has been interrupted with Ctrl-C
    -5 : Bad HTTP request
    -6 : Malformed SOAP envelope
    -7 : Malformed XML document
    -8 : HTTP error
    -9 : Unsupported operation
  -10 : Internal server error
  -11 : WSDL Generation failed
  -12 : WSDL Service not found
  -13 : Reserved
  -14 : Incoming request overflow
  -15 : Server was not started
  -16 : Request still in progress
  -17 : Stax response error
  -18 : Input request handler error
  -19 : Output request handler error
  -20 : WSDL handler error
  -21 : SOAP Version mismatch
  -22 : SOAP header not understood
  -23 : Deserialization error
 

Global option flags for SetOption and GetOption:

Flag Client or Server Description
readwritetimeout Client Defines the default maximum time in seconds a client, a HTTP request/response and a TCP request/response have to wait before raising an error that the server doesn't return or accept data. A value of -1 means infinite wait. The default is -1.
connectiontimeout Client Defines the default maximum time in seconds a client, a HTTPRequest and a TCPRequest have to wait for the establishment of a connection with a server.
A value of -1 means infinite wait. The default is 30 seconds for non-Windows, 5 seconds for Windows.
maximumresponselength Both Defines the maximum authorized size in KBytes for a client, server, HTTP or TCP response, before a break (when it stops and returns from the function because the amount of data surpassed the maximumresponselength.) A value of -1 means no limit. The default is -1.
wsdl_decimalsize Server Defines whether the precision and scale of a DECIMAL variable will be taken into account during the WSDL generation. See Notes on WSDL Generation Options below. A value of zero means FALSE. The default is TRUE.
wsdl_arraysize Server Defines whether the size of a BDL array will be taken into account during the WSDL generation. See Notes on WSDL Generation Options below.
A value of zero means FALSE. The default is TRUE.
wsdl_stringsize Server Defines whether the size of a CHAR or VARCHAR variable will be taken into account during the WSDL generation. See Notes on WSDL Generation Options below. A value of zero means FALSE. The default is TRUE.
http_invoketimeout
deprecated		 Client Defines the default maximum time in seconds a client has to wait before the client connection raises an error because the server is not responding. A value of -1 means that it has to wait until the server responds. The default is -1.

Important: Deprecated - use readwritetimeout
tcp_connectiontimeout
deprecated		 Client
Defines the default maximum time in seconds a client has to wait for the establishment of a TCP connection with a server. A value of -1 means infinite wait. The default is 30 seconds for non-Windows, 5 seconds for Windows.

Important: Deprecated - use connectiontimeout
SoapModuleURI Both Defines the SOAP role of a Genero application with an URI to identify it along a SOAP message path. Default value is NULL.

Back to the top

Notes on WSDL Generation Options

  1. For a BDL type DECIMAL(5,2), when "wsdl_decimalsize" is TRUE, the generated WSDL file contains the total size and the size of the fractional part of the decimal: 
    <types>
       <schema xmlns="http://www.w3.org/2001/XMLSchema"
               targetNamespace="http://www.mycompany.com/types/">
          <simpleType name="echoDecimal5_2_a_dec5_2_out_FGLDecimal">
             <restriction base="decimal">
                <totalDigits value="5" /> 
                <fractionDigits value="2" /> 
             </restriction>
          </simpleType>
       </schema>></types>
    <message name="echoDecimal5_2">
      <part name="dec5_2" type="f:echoDecimal5_2_a_dec5_2_in_FGLDecimal" /> 
    </message>

    When "wsdl_decimalsize" is FALSE, the total size and the size of the fractional part are not mentioned:

    <message name="echoDecimal5_2">
      <part name="dec5_2" type="xsd:decimal" />     
    </message>
  2. If the WSDL file does not contain the size, the client application has no way of knowing the size. In this case, a default value for the size is generated. For example, the exported server type DECIMAL(5,2) becomes a DECIMAL(32) on the client side.
  3. It is better to keep the options "wsdl_arraysize", "wsdl_stringsize", "wsdl_decimalsize" set to TRUE so that the BDL client application can do exact type mapping. The default for all three options is TRUE.
  4. When setting a facet constraint attribute on a simple datatype, the generation of the WSDL will take this attribute into account even if an option has been set to perform the opposite.
  5. When setting one facet constraint attribute, all of the default constraint attributes won't be generated anymore unless you specify them as facet constraint attributes.

Back to the top