Universal Resource Locators, or URLs, identify documents, such as HTML pages, available from SOAP or HTTP web services. The URLs used in SQL Anywhere follow the patterns familiar to you from browsing the web. Users browsing through a database server need not be aware that their requests are not being handled by a traditional standalone web server.

Although standard in format, SQL Anywhere database servers interpret URLs differently than standard web servers. The options you specify when you start the database server also affect their interpretation.

The general syntax of the URL is as follows:

{ http | https }://[ user:password@ ]host[ :port ][ /dbn ]/service-name[ path | ?searchpart ]

The following is an example URL: http://localhost:80/demo/XMLtable.

User and password

When a web service requires authentication, the user name and password can be passed directly as part of the URL by separating them with a colon and prepending them to the host name, much like an email address.

Host and port

Like all standard HTTP requests, the start of the URL contains the host name or IP number and, optionally, a port number. The IP address or host name, and port, should be the one on which your server is listening. The IP address is the address of a network card in the computer running SQL Anywhere. The port number will be the port number you specified using the -xs option when you started the database server. If you did not specify a port number, the default port number for that type of service is used. For example, the server listens by default on port 80 for HTTP requests. See -xs server option.

Database name

The next token, between the slashes, is usually the name of a database. This database must be running on the server and must contain web services.

The default database is used if no database name appears in the URL and the database name was not specified using the DBN connection parameter to the -xs server option.

The database name can be omitted only if the database server is running only one database, or if the database name was specified using the DBN connection parameter to the -xs option.

Service name

The next portion of the URL is the service name. This service must exist in the specified database. The service name can extend beyond the next slash character because web service names can contain slash characters. SQL Anywhere matches the remainder of the URL with the defined services.

If the URL provides no service name, then the database server looks for a service named root. If the named service, or the root service, is not defined, then the server returns a 404 Not Found error.

Parameters

Depending on the type of the target service, parameters can be supplied in different ways. Parameters to HTML, XML, and RAW services can be passed in any of the following ways:

Parameters to SOAP services must be included as part of a standard SOAP request. Values supplied in other ways are ignored.

URL path

To access parameter values, parameters must be given names. These host variable names, prefixed with a colon (:), can be included in the statement that forms part of the web service definition.

For example, suppose you define the following stored procedure:

CREATE PROCEDURE Display (IN ident INT )
BEGIN
    SELECT ID, GivenName, Surname FROM Customers
    WHERE ID = ident;
END;

A statement that calls the stored procedure requires a customer identification number. Define the service as follows:

CREATE SERVICE DisplayCustomer
TYPE 'HTML'
URL PATH ELEMENTS
AUTHORIZATION OFF
USER DBA 
AS CALL Display( :url1 );

An example of a URL for this is:  http://localhost:80/demo/DisplayCustomer/105.

The parameter 105 is passed as url1 to the service. The clause URL PATH ELEMENTS indicates that parameters separated by slashes should be passed as parameters url1, url2, url3, and so on. Up to 10 parameters can be passed in this way.

Since there is only one parameter to the Display procedure, the service could have been defined like this:

CREATE SERVICE DisplayCustomer
TYPE 'HTML'
URL PATH ON
AUTHORIZATION OFF
USER DBA 
AS CALL Display( :url );

In this case, the parameter 105 would be passed as url to the service. The clause URL PATH ON indicates that everything after the service name should be passed as a single parameter called url. So in the following URL, the string 105/106 would be passed as url (and a SQL error would result since the Display stored procedure requires an integer value).

 http://localhost:80/demo/DisplayCustomer/105/106

For more information about variables, see Working with variables.

Parameters can also be accessed using the HTTP_VARIABLE function. See HTTP_VARIABLE function [HTTP].

URL searchpart

Another method for passing parameters is through the URL searchpart mechanism. A URL searchpart consists of a question mark (?) followed by name=value pairs separated by ampersands (&). The searchpart is appended to the end of a URL. The following example shows the general format:

http://server/path/document?name1=value1&name2=value2

GET requests are formatted in this manner. If present, the named variables are defined and assigned the corresponding values.

For example, a statement that calls the stored procedure ShowSalesOrderDetail requires both a customer identification number and a product identification number:

CREATE SERVICE ShowSalesOrderDetail
TYPE 'HTML'
URL PATH OFF
AUTHORIZATION OFF
USER DBA 
AS CALL ShowSalesOrderDetail( :customer_id, :product_id );

An example of a URL for this is:  http://localhost:80/demo/ShowSalesOrderDetail?customer_id=101&product_id=300.

If you have URL PATH set to ON or ELEMENTS, additional variables are defined. However, the two are usually otherwise independent. You can allow variables to be used in requested URLs by setting URL PATH to ON or ELEMENTS. The following example illustrates how the two can be mixed:

CREATE SERVICE ShowSalesOrderDetail2
TYPE 'HTML'
URL PATH ON
AUTHORIZATION OFF
USER DBA 
AS CALL ShowSalesOrderDetail( :customer_id, :url );

In the following example, both searchpart and URL path are used. The value 300 is assigned to url and 101 is assigned to customer_id.

 http://localhost:80/demo/ShowSalesOrderDetail2/300?customer_id=101

This can also be expressed using searchpart only in the following manner.

 http://localhost:80/demo/ShowSalesOrderDetail2/?customer_id=101&url=300

This then leads to the question of what happens when both are specified for the same variable. In the following example, first 300 and then 302 are assigned to url in sequence and it is the last assignment that takes precedence.

 http://localhost:80/demo/ShowSalesOrderDetail2/300?customer_id=101&url=302

For more information about variables, see Working with variables.

Parameters can also be accessed using the HTTP_VARIABLE function. See HTTP_VARIABLE function [HTTP].