# 3. Quick Start & Tours

Chapter Contents | Prev | Next
Keyword Search:
www.openlinksw.com
docs.openlinksw.com
Book Home
Contents
Preface
Quick Start & Tours
Where to Start
Client Connections
Virtual Database Server
Web Server
WebDAV
Web Services
Exposing Persistent Stored Modules as Web Services
Publishing Stored Procedures as Web Services XML Query Templates Publishing VSE's as Web Services
VSMX - Virtuoso Service Module for XML
SQL to XML
NNTP
Dynamic Web Pages
VSP Examples
Third-Party Runtime Typing, Hosting & User Defined Types
Troubleshooting Tips

## 3.7. Exposing Persistent Stored Modules as Web Services

Virtuoso SQL stored procedures and functions can be exposed as SOAP services very simply from Virtuoso, whether they are native Virtuoso or on remote data sources. This powerful ability means that any database servers already existing within an organisation can easily become a component in an eBusiness solution using Virtuoso. All you need is a few simple steps that typically take mere minutes to complete:

- Choose your stored procedure(s)

  The procedures that you want to expose can either be native Virtuoso stored procedures, or remote stored procedures that can be linked in using the Remote Procedures user interface.

- Choose a virtual directory

  Because SOAP services need to be exposed and accessed via HTTP a Virtuoso virtual directory must be used. Either use the existing SOAP virtual directory or create a new one.

- Publish procedures to virtual directory

  The user specified as SOAP account on the virtual directorymust have execute privileges on the procedures. Use the Publish options on the virtual directory user interface.

- Test the VSMX output

  Once procedures have been published as SOAP services they are automatically described by WSDL and testable using Virtuoso's VSMX feature.

XML Query Templates provide a direct way to store SQL in an XML file on the Virtuoso server that when executed, ie fetched from a web browser, actually returns the results of the query.

The C Interface chapter describes how users can define custom built-in functions, from C or other programming languages, that can be used from within Virtuoso PL. This also means that VSE's can also be published as a Web Service!

### 3.7.1. Publishing Stored Procedures as Web Services

#### 3.7.1.1. Choosing Stored Procedures to Expose

You can either expose native Virtuoso stored procedures (previously defined or newly created) using the CREATE PROCEDURE statement, or stored procedures from other database types can be linked into Virtuoso using an ODBC datasource.

Virtuoso lists available stored procedures for each catalog under the option: /Database/Databases/<catalog_name>/Stored Procedures from the menu of the Virtuoso Server Administration Interface. This list will also include any remote procedures already linked into Virtuoso.

To link a stored procedure from another database system we must first create a valid data source that leads to a connection to that database. Once verified proceed to the Remote Procedures page.

Figure: 3.7.1.1.1. Linking Procedures from Remote Datasources

The data source will be listed in the data sources list. Select the data source that you want to used, check the Username and Password fields and press the List button. The page will next require you to select the catalog/owner combination to refine the search list of procedures on the remote data source. Use the drop-down to select relevant option and press List Selected to list the available stored procedures.

Figure: 3.7.1.1.2. Linking Procedures from Remote Datasources

When the page returns you will be presented with a list of available remote procedures. You can link any of the listed procedures into Virtuoso by selecting them from the list and pressing the Link Selected button.

Figure: 3.7.1.1.3. Linking Procedures from Remote Datasources

You will be presented with a new page listing the chosen procedures and their data type information. This gives you an opportunity to alter the data type mappings that Virtuoso will use both internally and for any future interactions with the SOAP server. If you do not want to specify any special type information the details can be left as default.

Figure: 3.7.1.1.4. Linking Procedures from Remote Datasources

For each remote procedure you may change how they will be referenced within Virtuoso by making changes to the fields for Local Name, Database, and Schema fields. These fields define how you will find the linked procedure locally to Virtuoso only and do not affect the remote data source.

For each procedure there is an option to Use PL Wrapper. This option is required if your remote procedure is capable of returning a resultset that you want to process via Virtuoso.

Once the details are correct press the Link button to proceed to the next step: Defining Virtual Directories.

See Also:

Linking Remote Procedures

#### 3.7.1.2. Defining Virtual Directories

Before any procedures native or linked can be exposed as SOAP Services a location in HTTP space must be defined. The /WebDAV/HTTP Virtual Directories page lets you make a new URL Mappings. The HTTP Virtual Directories page should contain a table with a row for {Default Web Site}. Click on the Edit URL Mappings link for the {Default Web Site} line to begin defining a new SOAP mapping.

Figure: 3.7.1.2.1. Virtual Directories

You will be presented with a list of existing mappings. Press the Add Virtual Directory button to create a new mapping. You will then be presented with a list of templates. Select the SOAP template.

Figure: 3.7.1.2.2. Virtual Directories Mappings

You will then be presented with the main configuration page. Particular options to note are Listener Details and SOAP Options.

Figure: 3.7.1.2.3. Virtual Directories

Logical Path will be the path to which Virtuoso will respond for this virtual directory mapping. This is what will be placed on the URL. Physical Path or URL is to which Virtuoso will map the logical path. In either case you can use the Browse buttons to traverse the file systems graphically. Use the WebDAV Source Checkbox to instruct Virtuoso to use the WebDAV store for the physical location.

In SOAP Options you can use the Publish button to select Virtuoso stored procedures, or remotely linked procedures to be published as SOAP web services. Press this button to select the procedures previously linked. Click on the database where your procedure resides. The next page will list the procedures in that database. Select the procedures you want to link using the checkboxes on the left most column and finally click the Publish button to complete the task.

See Also:

Virtual Directories

#### 3.7.1.3. Publishing Procedures to a Virtual Directory

If you already have a virtual directory defined and know what procedures you want to expose as web services you will have to repeat some of the steps in the section above. From the menu select /WebDAV/The HTTP Virtual Directories. Click on the Edit URL mappings link for the site that you want to edit. You will find the list of previously existing mappings, from which you can select the mapping that you want to edit by pressing on the edit link on the last column of the table.

Figure: 3.7.1.3.1. Virtual Directories

When the virtual directory configuration page is displayed scroll down to the SOAP Options section and use the Publish/UnPublish buttons to expose/hide your procedures and XML Templates as required.

Figure: 3.7.1.3.2. Publish/UnPublish Buttons

You will be presented with a screen for selecting the procedures or XML templates. For selecting the procedures you first have to select the appropriate catalogue that contains the procedure that you want to publish. For the XML Templates you simply select the template using the checkbox and provide an Export As name to choose the new SOAP name that this XML template will be refered as.

Figure: 3.7.1.3.3. Choosing Procedure and XML Templates to Publish

#### 3.7.1.4. Testing SOAP Services Using VSMX

Virtual directory definitions have a Logical Path field, which is reference in URL to find the correct SOAP services. If you connect to Virtuoso on http://localhost:8890/, and defined your virtual directory with the logical path of /mysoap then you will be able to test the following URLs:

- http://localhost:8890/mysoap/services.wsdl
- http://localhost:8890/mysoap/services.vsmx

The WSDL description is a standards-based description of the Web Services available from /mysoap. The VSMX page is a Virtuoso generated test page allowing you to test SOAP services. This feature should improve your development time.

See Also:

VSMX; SOAP; WSDL.

### 3.7.2. XML Query Templates

Virtuoso XML templates allow execution of SQL/XML queries over HTTP to obtain an XML document in response and/or perform some operation in the database using updategrams. XML templates can be executed from within Virtuoso procedure language using the xml_template() function. XML templates support two types of action: SQL based or updategram based. SQL query based templates must contain the FOR XML clause used in a SELECT statement and hence cannot update the database. Updates to the database can only occur from an updategram. The XML document returned from calling an XML template can be served either raw, or transformed using XSLT.

XML templates provide quick easy access to results from a SQL query as usual, but now this can be saved to a file. The results are not saved, just the query definition. You can use this feature to rapidly produce dynamic reports that can potentially be rendered in different ways by providing an alternate stylesheet. The report can be refined on the fly by providing parameters for the query. The output is reachable via HTTP directly by providing the URL to the template.

See Also:

The XML Templates Section

XML Templates can also be published just like normal store procedures. This is achieved by using a PL wrapper around the XML template. Then the store procedure is published in the normal way.

Stylesheets transformations with be inactive for published XML templates invoked from SOAP.

See Also:

The Publishing Stored Procedures Section above for a further description of publishing XML Templates.

### 3.7.3. Publishing VSE's as Web Services

The Virtuoso distribution includes the sample VSE, bif_sample.c. It is thus possible to create a function such as:

    .....
    static caddr_t
    bif_hello_world (caddr_t * qst, caddr_t * err_ret, state_slot_t ** args)
    {
      return box_dv_short_string ("Hello world.");
    }
    ....

Then declare it in the init_func() by adding the following code:

    ...
      bif_define_typed ("hello_world", bif_hello_world, &bt_any);
    ...

The next step is creating a stored procedure that calls this function and you are back to publishing a Virtuoso stored procedure again, as in the above section.

    create procedure BIF_HELLO_WORLD () { return hello_world (); };

See Also:

The C Interface Chapter

Previous Web Services | Chapter Contents | Next VSMX - Virtuoso Service Module for XML