<HTML lang=en dir=ltr xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
<HEAD>
<TITLE>Creating a Tcl Web Service</TITLE>
<META http-equiv=Content-Type content="text/html; charset=utf-8">
<META content="Creating a Tcl Web Service" name=KEYWORDS>
</HEAD>
<BODY>
<H1>Creating a Tcl Web Service</H1>
<TABLE class=toc id=toc>
<TR>
<TD>
<DIV id=toctitle>
<H2>Contents</H2></DIV>
<UL>
<LI class=toclevel-1><A href="#Loading_the_Webservices_Server_Package"><SPAN
class=tocnumber>1</SPAN> <SPAN class=toctext>Loading the Webservices
Server Package</SPAN></A>
<LI class=toclevel-1><A href="#Defining_a_Service"><SPAN
class=tocnumber>2</SPAN> <SPAN class=toctext>Defining a
Service</SPAN></A>
<LI class=toclevel-1><A href="#Defining_an_Operation_.28aka_a_Service_Procedure.29"><SPAN
class=tocnumber>3</SPAN> <SPAN class=toctext>Defining an Operation (aka
a Service Procedure)</SPAN></A>
<LI class=toclevel-1><A href="#Declaring_Complex_Types"><SPAN
class=tocnumber>4</SPAN> <SPAN class=toctext>Declaring Complex
Types</SPAN></A> </LI></UL></TD></TR></TBODY></TABLE>
<A name=Loading_the_Webservices_Server_Package></A>
<H2>Loading the Webservices Server Package </H2>
<P>To load the webservices server package, do: </P><PRE> package require WS::Server
</PRE>
<P>This command will only load the server the first time it is used, so it
causes no ill effects to put this in each file declaring a service or service
procedure. </P>
<h3>Using as part of TclHttpd</h3>
<P>
The Web Services package, WS::Server, is not a standalone application, but rather is designed
be a "module" of TclHttpd.
The following command is normally placed in httpdthread.tcl:
</P>
<h3>Embedding in a Standalone Application</h3>
<P>
To embed a Web Service into an application, the application needs to be event
driven and you also need to use the <B>WS::Embeded</b> package. You also must
define the service with the <i>-mode=embedded</i> option.
</P>
<P>
See also
<A HREF="Embedded Web Service.html">Embeding a Web Service into an application</A>.
</P>
<HR>
<A name=Defining_a_Service></A>
<H2>Defining a Service </H2>
<P>
The code that defines a service is normally placed in one or more files in the custom directory.
</P>
<P><B>Procedure Name : <I>::WS::Server::Service</I></B> </P>
<P><B>Description</B> : Declare a Web Service, the following URLs will
exist </P><PRE> /service/<ServiceName>
Displays an HTML page describing the service
/service/<ServiceName>/wsdl
Returns a WSDL describing the service
/service/<ServiceName>/op
Invoke an operation
</PRE>
<P><B>Arguments</B> : this procedure uses position independed arguments,
they are: </P><PRE> -host - The host name for this serice
Defaults to "localhost"
-decription - The HTML description for this service
-xmlnamespace - Extra XML namespaces used by the service
-service - The service name (this will also be used for
the Tcl namespace of the procedures that implement
the operations.
-premonitor - This is a command prefix to be called before
an operation is called. The following arguments are
added to the command prefix:
PRE serviceName operationName operArgList
-postmonitor - This is a command prefix to be called after
an operation is called. The following arguments are
added to the command prefix:
POST serviceName operationName OK|ERROR results
-inheaders - List of input header types.
-outheaders - List of output header types.
-checkheader - Command prefix to check headers.
If the call is not to be allowed, this command
should raise an error.
The signature of the command must be:
cmd \
service \
operation \
caller_ipaddr \
http_header_list \
soap_header_list
-mode - Mode that service is running in. Must be one of:
tclhhtpd -- running inside of tclhttpd or an
evironment that supplies a
compatilbe Url_PrefixInstall
and Httpd_ReturnData commands
embedded -- using the ::WS::Embedded package
-ports - List of ports for embedded mode. Default: 80
NOTE -- a call should be to
::WS::Embedded::Listen for each port
in this list prior to this call
</PRE>
<P><B>Returns</B> : Nothing </P>
<P><B>Side-Effects</B> : None </P>
<P><B>Exception Conditions</B> : </P><PRE> <I>MISSREQARG</I> -- Missing required arguements
</PRE>
<P><B>Pre-requisite Conditions</B> : None </P>
<HR>
<A name=Defining_an_Operation_.28aka_a_Service_Procedure.29></A>
<H2>Defining an Operation (aka a Service Procedure) </H2>
<P><B>Procedure Name : <I>::WS::Server::ServiceProc</I></B> </P>
<P><B>Description</B> : Register an operation for a service and declare the
procedure to handle the operations. </P>
<P><B>Arguments</B> : </P><PRE> <I>ServiceName </I> -- Name of the service this operation is for
<I>NameInfo </I> -- List of three elements:
1) OperationName -- the name of the operation
2) ReturnType -- the type of the procedure return,
this can be a simple or complex type
3) Description -- description of the return method
<I>Arglist </I> -- List of argument definitions,
each list element must be of the form:
1) ArgumentName -- the name of the argument
2) ArgumentTypeInfo -- -- A list of:
{type typeName comment commentString}
typeName can be any simple or defined type.
commentString is a quoted string describing the field
<I>Documentation</I> -- HTML describing what this operation does
<I>Body </I> -- The tcl code to be called when the operation is invoked. This
code should return a dictionary with <OperationName>Result as a
key and the operation's result as the value.
</PRE>
<P><B>Returns</B> : Nothing </P>
<P><I>Side-Effects</I> : </P><PRE> A proceedure named "<ServiceName>::<OperationName>" defined
A type name with the name <OperationName>Result is defined.
</PRE>
<P><I>Exception Conditions</I> : None </P>
<P><I>Pre-requisite Conditions</I> : ::WS::Server::Server must have
been called for the ServiceName </P>
<HR>
<A name=Declaring_Complex_Types></A>
<H2>Declaring Complex Types </H2>
<P>See: <A
title="Creating a Web Service Type from Tcl"
href="Creating a Web Service Type.html">Creating
a Web Service Type from Tcl</A> </P>
</BODY>
</HTML>