Forum OpenACS Development: Re: Tcl Web Services Toolkit: TWiST

Please respect that TWiST and tWSDL are part of an independent project. I intend to be responsive in maintaining the code and providing examples of use and documentation. However I use a very simple framework to do this, and it works with Tcl, AOLserver and OpenACS as-is.

Project Home: http://code.google.com/p/twsdl/

1) I'm not sure why you would need to directly source this file, what exactly did you do, or what instructions did you follow? What is the special call you tried? What were you expecting to happen? You should only source the top level init.tcl file, which will handle startup:

http://twsdl.googlecode.com/svn/trunk/init.tcl

You might edit a local configuration file to remove any unneeded packages:

http://twsdl.googlecode.com/svn/trunk/packages/tws/tcl/tws-local-conf.tcl

For instance, you can remove the tdom package if it is already loaded in OpenACS. (Just edit the package list in the above file.) Also StockQuoter isn't needed.

2) Which global variables? Do you mean namespace vars? TWiST and tWSDL operate on a database of information that I call WSDB. In short there is lots of information and procedures behind the scene. In fact, a lot of code is autogenerated from the API calls. This info/procs are 'stored' in Tcl namespaces. NSVs lack structure, they are just shared arrays. The only way to understand the WSDB is to look at it in a running server. How? Link the inspect package somewhere where you can look at what is in the database (::wsdb::*)

http://twsdl.googlecode.com/svn/trunk/packages/inspect/www/

3) No, please don't do this. tWSDL and TWiST are library code, and a completely separate project. An OpenACS package should use the API, but not modify. Of course, the OpenACS package should somehow download the correct release. I can help support this option, probably this needs some best practices input. Does any other package incorporate external code? It would be nice to see how it is done. Further documentation for the project is here:

http://twsdl.googlecode.com/svn/trunk/packages/doc/

4) the <ws>type and <ws>element procs are in the main trunk:

http://twsdl.googlecode.com/svn/trunk/packages/wsapi/tcl/ws-procs.tcl

Example of use is the stockquoter example (converted from tWSDL):

http://twsdl.googlecode.com/svn/trunk/packages/wsapi/www/stockquoter/index.tcl

When you get TWiST sourced, you can link the wsapi/www directory under pageroot to test things out.

Also note that I have some promised upgrades to tWSDL and TWiST in dealing with procedures which take or return arrays or lists, or lists of arrays or lists. I thought this was going to be a simple process, but I'm taking the opportunity to simplify and generalize the code. It's looking good, maybe the end of this week. Once this is done it should be very simple to extend this to cover ns_sets as input/output (One short procedure). Documentation overhaul will start once this is finished.

To use it I manually have to link the WWW directory. This is not possible with an OpenACS package as you cannot know where the TWIST is installed in the first place. Why not break your package up into something that you unzip in the root directory of the server and which splits into the /tcl directory just as now, but also unzips relative links into the www directory, so at least you can access the files. Something like /www/twsdl/wsdl (as an example).

And for the documentation, at the moment I always have to manually go into the tcl directory to find the procedure. This is why I would love to exchange all occurances of "proc ::" with "ad_proc ::", so at least the procedure is avialable for browsing in the ACS API and I do not have to go back to the shell, go to the directory, open the file,search for the procedure, look what it does and what variables it expects and what variables it returns. This makes development really burdensome 😊. This could be quickly fixed by you however. Just have a wrapper in init.tcl like:

if [lsearch [info procs ad_proc] ad_proc] <0} {
# insert the pass through definition for proc here
}

and then replace all instance of proc with ad_proc.

My suggestion for ad_proc also and solemnly was referring to the procedures which we are actually using to create the webservices, not the auto generated code. Obviously that would be a little bit harder to achieve. Though I still think having support for < wsdl:documentation > would come in handy (but maybe it already does this and I just did not find in the documentation where). The way I would probably find ist useful:

< ws >type pattern datetime::year $yearAnchored xsd:integer documentation:"Year of the datetime"

Or use the way your hated (sorry 😊 ) ad_proc does it for procedures

< ws >proc ::datetime::DayNameFromNumber {
{DayNumber:datetime::dayNumber}
} {
Returns the day of the week for a given number
} {
return .....
} returns {DayName:datetime::dayName}

Please be not offended by this suggestion. If you don't like it throw it away. I would be pleased to see your suggestions for creation and integration of < wsdl:documentation > tags, especially using the < ws > procedure.

As mentioned before, I have no intention of taking over your code. I want to use it and make it easy to use in the environment I work with, which happens to be OpenACS. If you find the fact that I did this rude, please accept my apologies, as I have no intention of doing anything that might offend you (though, judging from the tone in your replies you are offended, for which I am sorry and just hope you will be able to accept my sincerest apologies).