153
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 153-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 153-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 153-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 153-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 153-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 153-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 153-7  GET_IN_PARAMETER_TYPES Function Parameters

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

Return Values

Table 153-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 153-9 GET_OUT_PARAMETER_TYPES Function Parameters

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

Return Values

Table 153-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 153-11 GET_OUTPUT_VALUES Function Parameters

Parameter	Description
call_handle	The instance of the Call.

Return Values

Table 153-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 153-13  GET_PORTS Function Parameters

Parameter	Description
service_handle	The service instance whose ports are returned

Return Values

Table 153-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 153-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 153-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 153-17  GET_RETURN_TYPE Function Parameters

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

Return Values

Table 153-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 153-19  GET_RETURN_TYPE Function Parameters

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

Return Values

Table 153-20   GET_RETURN_TYPE 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 153-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 153-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 153-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 153-24  RELEASE_SERVICE Procedure Parameters

Parameter	Description
service_handle	The Service 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 153-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 153-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.