service-name
Web service names can be any sequence of alphanumeric characters or slash (/), hyphen (-), underscore (_), period (.),
exclamation mark (!), tilde (~), asterisk (*), apostrophe ('), left parenthesis ((), or right parenthesis ()), except that
the service name must not begin or end with a slash (/) or contain two or more consecutive slashes (for example, //).

Unlike other services, you cannot use a slash (/) anywhere in a DISH service name.

TYPE clause
Identifies the type of the service where each service defines a specific response format. The type must be one of the
listed service types. There is no default value.

'SOAP'
The result set is returned as an XML payload known as a SOAP envelope. The format of the data may be further refined
using by the FORMAT clause. A request to a SOAP service must be a valid SOAP request, not just a general HTTP request. For
more information about the SOAP standards, see http://www.w3.org/TR/2000/NOTE-SOAP-20000508/.

'DISH'
A DISH service (Determine SOAP Handler) is a SOAP endpoint that references any SOAP service within its GROUP context.
It also exposes the interfaces to its SOAP services by generating a WSDL (Web Services Description Language) for consumption
by SOAP client toolkits.

'RAW'
The result set is sent to the client without any formatting. Utilization of this service requires that all content
markup is explicitly provided. Complex dynamic content containing current content with markup, JavaScript and images can be
generated on demand. The media type may be specified by setting the Content-Type response header using the sa_set_http_header
procedure. Setting the Content-Type header to 'text/html' is good practice when generating HTML markup to ensure that all
browsers display the markup as HTML and not text/plain. See Developing web service applications in an HTTP web server, and sa_set_http_header system procedure.

'HTML'
The result set is returned as an HTML representation of a table or view.

'JSON'
The result set is returned in JavaScript Object Notation (JSON). For more information about JSON, see http://www.json.org/.

'XML'
The result set is returned as XML. If the result set is already XML, no additional formatting is applied. Otherwise,
it is automatically formatted as XML. As an alternative approach, a RAW service could return a select using the FOR XML RAW
clause having set a valid Content-Type such as text/xml using sa_set_http_header procedure. See sa_set_http_header system procedure.

GROUP clause
A DISH service without a GROUP clause exposes all SOAP services defined within the database. By convention, the SOAP
service name can be composed of a GROUP and a NAME element. The name is delimited from the group by the last slash character.
For example, a SOAP service name defined as 'aaa/bbb/ccc' is 'ccc', and the group is 'aaa/bbb'. Delimiting a DISH service using this convention is invalid. Instead, a GROUP clause is applied to specify the group of SOAP
services for which it is to be the SOAP endpoint.

Note

Slashes are converted to underscores within the WSDL to produce valid XML. Use caution when using a DISH service that does
not specify a GROUP clause such that it exposes all SOAP services that may contain slashes. Use caution when using groups
in conjunction with SOAP service names that contain underscores to avoid ambiguity.

DATATYPE clause
Applies to SOAP services only. When DATATYPE OFF is specified, SOAP input parameters and response data are defined as
XMLSchema string types. In most cases, true data types are preferred because it negates the need for the SOAP client to cast
the data prior to computation. Parameter data types are exposed in the schema section of the WSDL generated by the DISH service.
Output data types are represented as XML schema type attributes for each column of data.

The following values are permitted for the DATATYPE clause:

ON
Generates data typing of input parameters and result set responses.

OFF
All input parameters and response data are typed as XMLSchema string. (default)

URL clause
Determines whether URL paths are accepted and, if so, how they are processed. Applies to XML, HTML, JSON, and RAW service
types. PATH is optional in the syntax and is ignored.

OFF
Indicates that the service name in a URL request must not be followed by a path. OFF is the default setting. For example,
the following form will be disallowed due to the path elements /aaa/bbb/ccc.

http://<host-name>/<service-name>/aaa/bbb/ccc

Suppose that CREATE SERVICE echo URL PATH OFF was specified when creating the web service. A URL similar to http://localhost/echo?id=1 produces the following values:

HTTP_VARIABLE('id') == 1,
HTTP_HEADER('@HTTPQUERYSTRING') == id=1

ON
Indicates that the service name in a URL request can be followed by a path. The path is value is returned by querying
a dedicated HTTP variable named URL. A service can be defined to explicitly provide the URL parameter or it may be retrieved using the HTTP_VARIABLE function.
For example, the following form is allowed:

http://<host-name>/<service-name>/aaa/bbb/ccc

Suppose that CREATE SERVICE echo URL PATH ON was specified when creating the web service. A URL similar to http://localhost/echo/one/two?id=1 produces the following values:

ELEMENTS
Indicates that the service name in a URL request may be followed by a path. The path is obtained in segments by specifying
a single parameter keyword URL1, URL2, and so on. Each parameter may be retrieved using the HTTP_VARIABLE or NEXT_HTTP_VARIABLE functions. These iterator functions
can be used in applications where a variable number of path elements can be provided. For example, the following form is allowed:

http://<host-name>/<service-name>/aaa/bbb/ccc

Suppose that CREATE SERVICE echo URL PATH ELEMENTS was specified when creating the web service. A URL similar to http://localhost/echo/one/two?id=1 produces the following values:

Up to 10 elements can be obtained. A NULL value is returned if the corresponding element is not supplied. In the above example,
HTTP_VARIABLE('URL3') returns NULL because no corresponding element was supplied.

The SOAP service format is dictated by the associated DISH service format specification when it is not specified by the SOAP
service. The default format is DNET.

SOAP requests should be directed to the DISH service (the SQL Anywhere SOAP endpoint) to leverage common formatting rules
for a group of SOAP services (SOAP operations). A SOAP service FORMAT specification overrides that of a DISH service. The
format specification of the DISH service is used when a SOAP service does not define a FORMAT clause. If no FORMAT is provided
by either service then the default is 'DNET'.

The following formats are supported for DISH and SOAP services:

'DNET'
The output is in a System.Data.DataSet compatible format for consumption by .NET client applications. (default)

'CONCRETE'
This output format is used to support client SOAP toolkits that are capable of generating interfaces representing
arrays of row and column objects but are not able to consume the DNET format. Java and .NET clients can easily consume this
output format.

The specific output format is exposed within the WSDL of a DISH service. For CONCRETE OFF or as a last resort, a CONCRETE
format for one or more SOAP services is represented as a SimpleDataset. Examining the WSDL, a SimpleDataset is composed of an array of rows composed of an array of any number of columns. This is not an ideal representation because
the specific column names and data types are not specified. It is recommended that SOAP services define a call to a stored
procedure that, in turn, defines a RESULT clause. A DISH service exposing SOAP services defined in this way can fully describe
the result set when generating the WSDL.

By default, EXPLICIT ON is assumed and the WSDL contains a specific Dataset entry for each SOAP service if the result set for a SOAP service can
be described. Each entry name is prefixed by the SOAP service name and an underscore. For example, a SOAP service named test produces a test_Dataset object specification containing the XMLSchema definitions for each of its column elements.

When EXPLICIT ON is specified (default), the WSDL describes an explicit DataSet element when the following criteria are met:

The CREATE SERVICE statement calls a stored procedure

A RESULT clause describing the columns and data types is specified in the stored procedure

When EXPLICIT OFF is specified, the WSDL describes the SimpleDataset element. This description does not provide the number of columns, column names or data types.

'XML'
The output is generated in an XMLSchema string format. The response is an XML document that requires further processing
by the SOAP client to extract column data. This format is suitable for SOAP clients that cannot generate intermediate interface
objects that represent arrays of rows and columns.

NULL
A NULL type causes the SOAP or DISH service to use the default behavior. The format type of an existing service is
overwritten when using the NULL type in an ALTER SERVICE statement.

AUTHORIZATION clause
Determines whether users must specify a user name and password through basic HTTP authorization when connecting to the
service. The default value is ON. If authorization is OFF, the AS clause is required for all services with the exception of
DISH, and a user must be specified with the USER clause. All requests are run using that user's account and permissions. If
AUTHORIZATION is ON, all users must provide a user name and password. Optionally, you can limit the users that are permitted
to use the service by providing a user or group name with the USER clause. If the user name is NULL, all known users can access
the service. The AUTHORIZATION clause allows your web services to use database authorization and permissions to control access
to the data in your database.

When the authorization value is ON, an HTTP client connecting to a web service uses basic authentication (RFC 2617) which
obfuscates the user and password information using base-64 encoding. It is recommended that you use the HTTPS protocol for
increased security.

ENABLE and DISABLE clauses
Determines whether the service is available for use. By default, when a service is created, it is enabled. When creating
or altering a service, you may include an ENABLE or DISABLE clause. Disabling a service effectively takes the service off
line. Later, it can be enabled using ALTER SERVICE with the ENABLE clause. An HTTP request made to a disabled service typically
returns a 404 Not Found HTTP status.

METHODS clause
Specifies the HTTP methods that are supported by the service. Valid values are DEFAULT, POST, GET, HEAD, PUT, DELETE,
and NONE. An asterisk (*) may be used as a short form to represent the POST, GET, and HEAD methods which are default request types for the RAW, HTML
and XML service types. The default method types for SOAP services are POST and HEAD. The default method types for DISH services
are GET, POST, and HEAD. Not all HTTP methods are valid for all the service types. The following table summarizes the valid
HTTP methods that can be applied to each service type:

Request type

Applies to service

Description

DEFAULT

all

Use DEFAULT to reset the set of request types to the default set for the given service type. It cannot be included in a list
with other request types.

POST

SOAP, DISH, RAW, HTML, XML

Enabled by default for SOAP, RAW, HTML and XML.

GET

DISH, RAW, HTML, XML

Enabled by default for DISH, RAW, HTML and XML.

HEAD

SOAP, DISH, RAW, HTML, XML

Enabled by default for SOAP, DISH, RAW, HTML and XML.

PUT

RAW, HTML, XML

Not enabled by default.

DELETE

RAW, HTML, XML

Not enabled by default.

NONE

all

Use NONE to disable access to a service. When applied to a SOAP service, the service cannot be directly accessed by a SOAP
request. This enforce exclusive access to a SOAP operation through a DISH service SOAP endpoint.

It is recommended that you specify METHOD NONE for each SOAP service.

*

DISH, RAW, HTML, XML

Same as specifying 'POST,GET,HEAD'.

For example, you can use either of the following clauses to specify that a service supports all HTTP method types:

METHODS '*,PUT,DELETE'
METHODS 'POST,GET,HEAD,PUT,DELETE'

To reset the list of request types for any service type to its default, you can use the following clause:

METHODS 'DEFAULT'

SECURE clause
Specifies whether the service should be accessible on a secure or non-secure listener. ON indicates that only HTTPS connections
are accepted, and that connections received on the HTTP port are automatically redirected to the HTTPS port. OFF indicates
that both HTTP and HTTPS connections are accepted, provided that the necessary ports are specified when starting the web server.
The default value is OFF.

USER clause
Specifies a database user, or group of users, with permissions to execute the web service request. A USER clause must
be specified when the service is configured with AUTHORIZATION OFF and should be specified with AUTHORIZATION ON. (the default)
An HTTP request made to a service requiring authorization results in a 401 Authorization Required HTTP response status. Based on this response, the web browser prompts for a user ID and password.

Caution

It is strongly recommended that you specify a USER clause when authorization is enabled (default). Otherwise, authorization
is granted to all users.

The USER clause controls which database user accounts can be used to process service requests. Database access permissions
are restricted to the privileges assigned to the user of the service.

statement
Specifies a command, such as a stored procedure call, to invoke when the service is accessed.

A DISH service is the only service that must either define a null statement, or not define a statement. A SOAP service must
define a statement. Any other SERVICE can have a NULL statement, but only if configured with AUTHORIZATION ON.

An HTTP request to a non-DISH service with no statement specifies the SQL expression to execute within its URL. Although authorization is required, this capability should not be
used in production systems because it makes the server vulnerable to SQL injections. When a statement is defined within the
service, the specified SQL statement is the only statement that can be executed through the service.

In a typical web service application, you use statement to call a function or procedure. You can pass host variables as parameters to access client-supplied HTTP variables.

The following statement demonstrates a procedure call that passes two host variables to a procedure named AuthenticateUser. This call presumes that a web client supplies the user_name and user_password variables: