1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
|
<HTML lang=en dir=ltr xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
<HEAD>
<TITLE>Using Web Service Options</TITLE>
<link rel="stylesheet" href="style.css" type="text/css" media="screen">
</HEAD>
<BODY>
<H1 class=firstHeading>Using Web Service Options</H1>
<TABLE class=toc id=toc>
<TR>
<TD>
<H2>Contents</H2></DIV>
<UL>
<li class="toclevel-1"><a href="#Overview"><span class="toctext">Overview</span></a>
</li><li class="toclevel-1"><a href="#Loading_the_Webservices_Utilities_Package"><span class="toctext">Loading the Webservices Utilities Package</span></a>
</li><li class="toclevel-1"><a href="#SetOption"> <span class="toctext">Access Routine</span></a>
</li><li class="toclevel-1"><a href="#Options"> <span class="toctext">Options</span></a>
<ul>
</li><li class="toclevel-2"><a href="#genOutAttr"> <span class="toctext">genOutAttr - generate attributes on outbound tags</span></a>
</li><li class="toclevel-2"><a href="#includeDirectory"> <span class="toctext">includeDirectory - disk directory to use for XSD includes when they can not be accessed via the Web.</span></a>
</li><li class="toclevel-2"><a href="#nsOnChangeOnly"> <span class="toctext">nsOnChangeOnly - only put namespace prefix when namespaces change</span></a>
</li><li class="toclevel-2"><a href="#parseInAttr"><span class="toctext">parseInAttr - parse attributes on inbound tags</span></a>
</li><li class="toclevel-2"><a href="#queryTimeout"> <span class="toctext">queryTimeout - set http(s) fetch timeout.</span></a>
</li><li class="toclevel-2"><a href="#StrictMode"> <span class="toctext">StrictMode - WSDL processing mode</span></a>
<li class="toclevel-2"><a href="#UseNS"> <span class="toctext">UseNS - put namespaces on field tags</span></a>
</li><li class="toclevel-2"><a href="#useTypeNs"> <span class="toctext">useTypeNs - use type's namespace prefix as prefix of elements</span></a>
</li><li class="toclevel-2"><a href="#suppressNS"> <span class="toctext">suppressNS - do not put a particular namespace prefix</span></a>
</li></ul>
</li></ul>
<P>
</P>
<A name=Overview></A>
<H2>Overview</H2>
</P>
<P>The Webservices Client and Server packages make use of the following options:
</p><ul>
<li><a href="#UseNS">UseNS</a>, when set the following options become relevant:
<ul>
<li><a href="#useTypeNs">useTypeNs</a>
</li><li><a href="#nsOnChangeOnly">nsOnChangeOnly</a>
</li><li><a href="#suppressNS">suppressNS</a>
</li></ul>
</li><li><a href="#StrictMode">StrictMode</a>
</li><li><a href="#parseInAttr">parseInAttr</a>
</li><li><a href="#genOutAttr">genOutAttr</a>
</li><li><a href="#includeDirectory">includeDirectory</a>
</li></ul>
<p></p>
<P>The attributes can be retrieved and set using <A href="#SetOption">::WS::Utils::SetOption</A>.</P>
<p>If called by the client side, the following options are overwritten and restored on any call:
<ul>
<li>genOutAttr</li>
<li>nsOnChangeOnly</li>
<li>parseInAttr</li>
<li>suppressNS</li>
<li>UseNS</li>
<li>useTypeNs</li>
<li>valueAttrCompatiblityMode</li>
</ul>
</p>
<HR>
<A name=Loading_the_Webservices_Utilities_Package></A>
<H2>Loading the Webservices Utilities Package </H2>
<P>To load the webservices server package, do: </P><PRE> package require WS::Utils
</PRE>
<P>This command will only load the utilities the first time it is used, so it
causes no ill effects to put this in each file using the utilties. </P>
<HR>
<A name=SetOption></A>
<H2>Access Routine </H2>
<P><B>Procedure Name : <I>::WS::Utils::SetOption</I></B> </P>
<P><B>Description : </B> Retrieve or set an option </P>
<P><B>Arguments :</B> </P>
<PRE>
<I>option</I> - name of the option
<I>value</I> - value of the option (optional)
</PRE>
<P><B>Returns : The value of the option</B> </P>
<P><B>Side-Effects : None</B> </P>
<P><B>Exception Conditions :None</B> </P>
<P><B>Pre-requisite Conditions : None</B> </P>
<HR>
<A name=genOutAttr></A>
<H2>genOutAttr - generate attributes on outbound tags </H2>
<P>
The <I>genOutAttr</I> option, if set to a "true" value,
will convert all dictionary keys of the entry for a given field tag to attribute value pairs
of the tag in the outbound XML.
For attributes in the "http://www.w3.org/2001/XMLSchema-instance" url, the key will be the attribute name prepended with two colons (e.g. <B>::type</B>) and the value will be the value of the attribute.
For attributes other than those in the "http://www.w3.org/2001/XMLSchema-instance" url, the key will be the attribute name and the value will be the value of the attribute.
The value of the tag will have a key determined by the <a href="#valueAttrCompatiblityMode"><I>valueAttrCompatiblityMode</I></a>.
</P>
<P>
The default value, "0", is for this option to be turned off.
</P>
<HR>
<p><a name="includeDirectory"></a>
</p><h2>includeDirectory - disk directory to use for XSD includes when they can not be accessed via the Web. </h2>
<p>
The <i>includeDirectory</i> option, if set, instructs TclWs to look in the specified directory for any XSD includes that can not be found via the web.
</p>
<p>
The default value, "{}", is for this option to be turned off.
</p>
<hr />
<p><a name="nsOnChangeOnly"></a>
</p><h2>nsOnChangeOnly - only put namespace prefix when namespaces change </h2>
<p>
The <i>nsOnChangeOnly</i> option, if set to a "true" value,
will only place namespace prefixes when the namespaces change.
</p>
<p>
This option is only relevant, if the option <a href="#UseNS">UseNS</a> is set.
</p>
<p>
The default value, "0", is for this option to be turned off.
</p>
<hr />
<A name=parseInAttr></A>
<H2>parseInAttr - parse attributes on inbound tags </H2>
<P>
The <I>parseInAttr</I> option, if set to a "true" value,
will convert all attributes of inbound field tags to dictionary entries for that tag.
For attributes in the "http://www.w3.org/2001/XMLSchema-instance" url, the key will be the attribute name prepended with two colons (e.g. <B>::type</B>) and the value will be the value of the attribute.
For attributes other than those in the "http://www.w3.org/2001/XMLSchema-instance" url, the key will be the attribute name and the value will be the value of the attribute.
The value of the tag will have a key determined by the <a href="#valueAttrCompatiblityMode"><I>valueAttrCompatiblityMode</I></a>.
</P>
<P>
The default value, "0", is for this option to be turned off.
</P>
<HR />
<p><a name="queryTimeout"></a></p>
<h2>queryTimeout - set http(s) query timeout</h2>
<p>
Timeout to any network query in ms.
The <A HREF="Calling_a_Web_Service.html#Config">client side package</a> has an option with the same functionality, which is used, when there is a call option context.
</p>
<p>Default value: 60000 (1 minuite).</p>
<HR />
<A name=StrictMode></A>
<H2>StrictMode - WSDL processing mode </H2>
<P>
The <I>StrictMode</I> option determines what happens when an error is detected in parsing a WSDL. The legal values are:
<UL>
<LI><B>debug</B></LI>
<LI><B>warning</B></LI>
<LI><B>error</B></LI>
</UL>
</P>
<P>
If the <I>StrictMode</I> is set to <B>debug</B> or <B>warning</B>,
a message is logged using the ::log package at that level and the error is then ignored.
</P>
<P>
If the <I>StrictMode</I> is set to any value other than <B>debug</B> or <B>warning</B>,
a message is logged using the ::log package at the <B>error</B> level and exception is generated.
</P>
<P>
The default value is <B>error</B>.
</P>
<P>
A major use of this is to ignore namespace imports in a WDSL that do not actually import any definitions.
</P>
<HR />
<A name=UseNS></A>
<H2>UseNS - put namespaces on field tags </H2>
<P>
The <I>UseNS</I> option, if set to a "true" value, will put a namespace alias on all field tags.
</P>
<P>
The default value, "1", is for this option to be turned on.
</P>
<HR>
<p><a name="useTypeNs"></a>
</p><h2>useTypeNs - use type's namespace prefix as prefix of elements </h2>
<p>
The <i>useTypeNs</i> option, if set to a "true" value,
will use the prefix of the type's namespace instead of the prefix of the element's namespace.
</p>
<p>
This option is only relevant, if the option <a href="#UseNS">UseNS</a> is set.
</p>
<p>
The default value, "0", is for this option to be turned off.
</p>
<hr />
<p><a name="suppressNS"></a>
</p><h2>suppressNS - do not put a given namespace prefix. </h2>
<p>
The <i>suppressNS</i> option, if set, will cause the given namespace
to never be used as a prefix (i.e. tags that would normally have had
the given prefix will not have any prefix).
</p>
<p>
This option is only relevant, if the option <a href="#UseNS">UseNS</a> is set.
</p>
<p>
The default value, "{}", is for this option to be turned off.
</p>
<hr />
<A name=valueAttrCompatiblityMode></A>
<H2>valueAttrCompatiblityMode - specify dictionary key for value when attributes are in use</H2>
<P>
This option is only meaningful when the
<i>parseInAttr</i> or <I>genOutAttr</I> option is set to a "true" value.
When set to a "true" value, the value of the tag will have a key of the null string (i.e. <B>{}</B>).
When set to a "false" value, the value of the tag will have a key of <B>::value</B>.
</P>
<P>
The default value, "0", is for this option to be turned off.
</P>
<HR>
</BODY>
</HTML>
|
