165 UTL_DBWS

The UTL_DBWS package provides database web services.

This chapter contains the following topics:

Using UTL_DBWS
- Supported Keys and Default Settings for Standard Call Properties
Summary of UTL_DBWS Subprograms

Using UTL_DBWS

Supported Keys and Default Settings for Standard Call Properties

Supported Keys and Default Settings for Standard Call Properties

Table 165-1 Supported Keys and Default Settings for Standard Call Properties

Key	Explanation of Value, Default value
`'USERNAME'`	User name for authentication.
`'PASSWORD'`	Password for authentication.
`'ENCODINGSTYLE_URI'`	Encoding style specified as a namespace URI. The default value is the SOAP 1.1 encoding http://schemas.xmlsoap.org/soap/encoding/.
`'OPERATION_STYLE'`	Standard property for operation style. Set to '`RPC`' if the operation style is RPC, '`DOCUMENT`' if the operation style is document.
`'SESSION_MAINTAIN'`	This boolean property is used by a service client to indicate whether or not it wants to participate in a session with a service endpoint.If this property is set to '`TRUE`', the service client indicates that it wants the session to be maintained. If set to '`FALSE`', the session is not maintained. The default value for this property is '`FALSE`'
`'SOAPACTION_USE'`	This boolean property indicates whether or not SOAPAction is to be used. The default value of this property is '`FALSE`'.
`'SOAPACTION_URI'`	Indicates the SOAPAction URI if the `SOAPACTION_USE` property is set to '`TRUE'`

Summary of UTL_DBWS Subprograms

Table 165-2 UTL_DBWS Subprograms

Subprogram	Description
CREATE_CALL Function	Creates a Call instance
CREATE_SERVICE Function	Creates a Service instance
GET_IN_PARAMETER_TYPES Function	Lists the XML type of the input parameters of the Call that is returned
GET_OUT_PARAMETER_TYPES Function	Lists the XML type of the output parameters of the Call that is returned
GET_OUTPUT_VALUES Function	Obtains the output arguments after a Call invocation
GET_PORTS Function	Lists the qualified names of all of the ports in a service
GET_PROPERTY Function	Returns the value of a particular property on a Call
GET_RETURN_TYPE Function	Lists the XML type that is returned by the given Call
GET_SERVICES Function	Lists the qualified names of the services defined in a WDSL document
INVOKE Function	Invokes a specific operation using a synchronous request-response interaction mode
RELEASE_ALL_SERVICES Procedure	Releases all Service instances
RELEASE_CALL Procedure	Releases a particular Call instance
RELEASE_SERVICE Procedure	Releases a particular Service instance
REMOVE_PROPERTY Procedure	Clears the value of a particular property on a Call
SET_PROPERTY Procedure	Sets the value of a particular property on a Call

CREATE_CALL Function

This procedure creates a Call instance.

Syntax

UTL_DBWS.CREATE_CALL (
   service_handle    SERVICE, 
   port_name         QNAME,
   operation_name    QNAME)
 RETURN CALL;

Parameters

Table 165-3 CREATE_CALL Function Parameters

Parameter	Description
`service_handle`	The Service instance to be called.
`port_name`	The `qualified name for the port. Use the first port if this is NULL`.
`operation_name`	The qualified name for the operation.

Return Values

Table 165-4 CREATE_CALL Return Values

Parameter	Description
`CALL`	Returns a handle to the Call instance.

CREATE_SERVICE Function

This procedure creates a Service instance.

Syntax

UTL_DBWS.CREATE_SERVICE(
   wsdl_document_location  URITYPE,
   service_name            QNAME)
  RETURN SERVICE;

Parameters

Table 165-5 CREATE_SERVICE Function Parameters

Parameter	Description
`wsdl_document_location`	The URL for the WSDL document location for the service
`service_name`	The qualified name for the service. Use the first service if this is `NULL`.

Return Values

Table 165-6 CREATE_SERVICE Return Values

Parameter	Description
`SERVICE`	Returns a handle to the Service instance.

GET_IN_PARAMETER_TYPES Function

This procedure lists the XML type of the input parameters of the Call that is returned.

Syntax

UTL_DBWS.GET_IN_PARAMETER_TYPES(
   call_handle    CALL) 
 RETURN QNAME_LIST;

Parameters

Table 165-7 GET_IN_PARAMETER_TYPES Function Parameters

Parameter	Description
`call_handle`	The Service instance whose input types are returned.

Return Values

Table 165-8 GET_IN_PARAMETER_TYPES Function Return Values

Parameter	Description
`QNAME_LIST`	The list of the XML type of the input parameters of the Call that is returned.

GET_OUT_PARAMETER_TYPES Function

This procedure lists the XML type of the output parameters of the Call that is returned.

Syntax

UTL_DBWS.GET_OUT_PARAMETER_TYPES(
   call_handle    CALL) 
 RETURN QNAME_LIST;

Parameters

Table 165-9 GET_OUT_PARAMETER_TYPES Function Parameters

Parameter	Description
`call_handle`	The Service instance whose output types are returned.

Return Values

Table 165-10 GET_OUT_PARAMETER_TYPES Function Return Values

Parameter	Description
`QNAME_LIST`	The list of the XML type of the input parameters of the Call that is returned.

GET_OUTPUT_VALUES Function

This procedure obtains the output arguments after a Call invocation.

Syntax

UTL_DBWS.GET_OUTPUT_VALUES(
   call_handle    CALL) 
 RETURN ANYDATA_LIST;

Parameters

Table 165-11 GET_OUTPUT_VALUES Function Parameters

Parameter	Description
`call_handle`	The instance of the Call.

Return Values

Table 165-12 GET_OUTPUT_VALUES Function Return Values

Parameter	Description
`ANYDATA_LIST`	Returns the output arguments in order.

GET_PORTS Function

This procedure lists the qualified names of all of the ports in a service.

Syntax

UTL_DBWS.GET_PORTS(
   service_handle    SERVICE)
 RETURN QNAME_LIST;

Parameters

Table 165-13 GET_PORTS Function Parameters

Parameter	Description
`service_handle`	The service instance whose ports are returned

Return Values

Table 165-14 GET_PORTS Function Return Values

Parameter	Description
`QNAME_LIST`	Returns a list of the qualified names of all ports in a service

GET_PROPERTY Function

This procedure returns the value of a particular property on a Call.

Syntax

UTL_DBWS.GET_PROPERTY(
   call_handle    CALL,
   key            VARCHAR2) 
  RETURN value VARCHAR2;

Parameters

Table 165-15 GET_PROPERTY Function Parameters

Parameter	Description
`call_handle`	The the instance of the Call.
`key`	The key for the property (see Using UTL_DBWS)

Return Values

Table 165-16 GET_PROPERTY Function Return Values

Parameter	Description
`value`	Returns the value of a particular property on a Call.

GET_RETURN_TYPE Function

This procedure lists the XML type that is returned by the given Call.

Syntax

UTL_DBWS.GET_RETURN_TYPE (
   call_handle    CALL) 
 RETURN QNAME;

Parameters

Table 165-17 GET_RETURN_TYPE Function Parameters

Parameter	Description
`call_handle`	The Service instance whose return type is returned.

Return Values

Table 165-18 GET_RETURN_TYPE Function Return Values

Parameter	Description
`QNAME`	The type that is returned.

GET_SERVICES Function

This function lists the qualified names of the services defined in a WDSL document.

Syntax

UTL_DBWS.GET_SERVICES(
   wsdl_document_location  URITYPE)
 RETURN QNAME_LIST;

Parameters

Table 165-19 GET_SERVICES Function Parameters

Parameter	Description
`wsdl_document_location`	The Service instance whose return type is returned.

Return Values

Table 165-20 GET_SERVICES Function Return Values

Parameter	Description
`QNAME_LIST`	A list of the qualified names of the services defined in the WSDL document.

INVOKE Function

This procedure invokes a specific operation using a synchronous request-response interaction mode.

Syntax

UTL_DBWS.INVOKE(
   call_handle    CALL, 
   input_params   ANYDATA_LIST) 
 RETURN ANYDATA;

Parameters

Table 165-21 INVOKE Function Parameters

Parameter	Description
`call_handle`	The Service instance whose return type is returned.
`input_params`	The input parameters for this invocation.

Return Values

Table 165-22 INVOKE Function Return Values

Parameter	Description
`ANYDATA`	`Returns the return value or NULL`.

RELEASE_ALL_SERVICES Procedure

This procedure releases all Service instances.

Syntax

UTL_DBWS.RELEASE_ALL_SERVICES;

RELEASE_CALL Procedure

This procedure releases a particular Call instance.

Syntax

UTL_DBWS.RELEASE_CALL(
   call_handle    CALL);

Parameters

Table 165-23 RELEASE_CALL Procedure Parameters

Parameter	Description
`call_handle`	The call instance that is to be released.

RELEASE_SERVICE Procedure

This procedure releases a particular Service instance.

Syntax

UTL_DBWS.RELEASE_SERVICE (
   service_handle     SERVICE);

Parameters

Table 165-24 RELEASE_SERVICE Procedure Parameters

Parameter	Description
service_handle	The call instance that is to be released.

Usage Notes

This will implicitly release all Call instances that have been created for this Service instance.

REMOVE_PROPERTY Procedure

This procedure clears the value of a particular property on a Call.

Syntax

UTL_DBWS.REMOVE_PROPERTY(
   call_handle   CALL, 
   key           VARCHAR2);

Parameters

Table 165-25 REMOVE_PROPERTY Procedure Parameters

Parameter	Description
`call_handle`	The call instance.
`key`	The key for the property (see Using UTL_DBWS).

SET_PROPERTY Procedure

This procedure sets the value of a particular property on a Call.

Syntax

UTL_DBWS.SET_PROPERTY(
   call_handle    CALL,
   key            VARCHAR2,
   value          VARCHAR2);

Parameters

Table 165-26 SET_PROPERTY Function Parameters

Parameter	Description
`call_handle`	The instance of the Call.
`key`	The key for the property (see Using UTL_DBWS).
`value`	The value for the property.