Debian Codegraph @

XMLMessage.html

raw
1 <HTML>
2 <HEAD>
3 <TITLE>DBIx::XMLMessage - XML Message exchange between DBI data sources</TITLE>
4 <LINK REV="made" HREF="mailto:">
5 </HEAD>
6
7 <BODY>
8
9 <!-- INDEX BEGIN -->
10
11 <UL>
12
13 <LI><A HREF="#NAME">NAME</A></LI>
14 <LI><A HREF="#SYNOPSIS">SYNOPSIS</A></LI>
15 <UL>
16
17 <LI><A HREF="#OUTBOUND_MESSAGE">OUTBOUND MESSAGE</A></LI>
18 <LI><A HREF="#INBOUND_MESSAGE">INBOUND MESSAGE</A></LI>
19 </UL>
20
21 <LI><A HREF="#DESCRIPTION">DESCRIPTION</A></LI>
22 <LI><A HREF="#SALES_PITCH">SALES PITCH</A></LI>
23 <LI><A HREF="#TEMPLATE_TAGS">TEMPLATE TAGS</A></LI>
24 <UL>
25
26 <LI><A HREF="#TEMPLATE">TEMPLATE</A></LI>
27 <LI><A HREF="#REFERENCE">REFERENCE</A></LI>
28 <LI><A HREF="#CHILD">CHILD</A></LI>
29 <LI><A HREF="#COLUMN">COLUMN</A></LI>
30 <LI><A HREF="#KEY">KEY</A></LI>
31 <LI><A HREF="#PARAMETER">PARAMETER</A></LI>
32 </UL>
33
34 <LI><A HREF="#TEMPLATE_TAG_ATTRIBUTES">TEMPLATE TAG ATTRIBUTES</A></LI>
35 <UL>
36
37 <LI><A HREF="#NAME">NAME</A></LI>
38 <LI><A HREF="#ACTION">ACTION</A></LI>
39 <LI><A HREF="#BLTIN">BLTIN</A></LI>
40 <LI><A HREF="#CARDINALITY">CARDINALITY</A></LI>
41 <LI><A HREF="#DATATYPE">DATATYPE</A></LI>
42 <LI><A HREF="#DEBUG">DEBUG</A></LI>
43 <LI><A HREF="#DEFAULT">DEFAULT</A></LI>
44 <LI><A HREF="#EXPR">EXPR</A></LI>
45 <LI><A HREF="#FACE">FACE</A></LI>
46 <LI><A HREF="#GENERATE_PK">GENERATE_PK</A></LI>
47 <LI><A HREF="#HIDDEN">HIDDEN</A></LI>
48 <LI><A HREF="#MAXROWS">MAXROWS</A></LI>
49 <LI><A HREF="#PARENT_NAME">PARENT_NAME</A></LI>
50 <LI><A HREF="#PROC">PROC</A></LI>
51 <LI><A HREF="#RTRIMTEXT">RTRIMTEXT</A></LI>
52 <LI><A HREF="#TABLE">TABLE</A></LI>
53 <LI><A HREF="#TOLERANCE">TOLERANCE</A></LI>
54 <LI><A HREF="#WHERE_CLAUSE">WHERE_CLAUSE</A></LI>
55 </UL>
56
57 <LI><A HREF="#METHODS">METHODS</A></LI>
58 <UL>
59
60 <LI><A HREF="#new">new</A></LI>
61 <LI><A HREF="#set_handlers">set_handlers</A></LI>
62 <LI><A HREF="#prepare_template">prepare_template</A></LI>
63 <LI><A HREF="#prepare_template_from_file">prepare_template_from_file</A></LI>
64 <LI><A HREF="#input_xml">input_xml</A></LI>
65 <LI><A HREF="#input_xml_file">input_xml_file</A></LI>
66 <LI><A HREF="#populate_objects">populate_objects</A></LI>
67 <LI><A HREF="#rexec">rexec</A></LI>
68 <LI><A HREF="#output_message">output_message</A></LI>
69 </UL>
70
71 <LI><A HREF="#SEE_ALSO">SEE ALSO</A></LI>
72 <LI><A HREF="#AUTHORS">AUTHORS</A></LI>
73 </UL>
74 <!-- INDEX END -->
75
76 <HR>
77 <P>
78 <H1><A NAME="NAME">NAME</A></H1>
79 <P>
80 DBIx::XMLMessage - XML Message exchange between DBI data sources
81
82 </P>
83 <P>
84 <HR>
85 <H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
86 <P>
87 <HR>
88 <H2><A NAME="OUTBOUND_MESSAGE">OUTBOUND MESSAGE</A></H2>
89 <P>
90 <PRE> #!/usr/bin/perl
91 </PRE>
92 </P>
93 <P>
94 <PRE> use DBI;
95 use DBIx::XMLMessage;
96 </PRE>
97 </P>
98 <P>
99 <PRE> # Template string
100 my $tpl_str =&lt;&lt; &quot;_EOT_&quot;;
101 &lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot; ?&gt;
102 &lt;TEMPLATE NAME='SysLogins' TYPE='XML' VERSION='1.0' TABLE='syslogins'&gt;
103 &lt;KEY NAME='suid' DATATYPE='NUMERIC' PARENT_NAME='OBJECT_ID' /&gt;
104 &lt;COLUMN NAME='LoginId' EXPR='suid' DATATYPE='NUMERIC' /&gt;
105 &lt;COLUMN NAME='PasswordDate' EXPR='pwdate' DATATYPE='DATETIME'
106 BLTIN=&quot;fix_gmdatetime&quot; /&gt;
107 &lt;CHILD NAME='SysUsers' TABLE='sysusers'&gt;
108 &lt;KEY NAME='suid' PARENT_NAME='LoginId' DATATYPE='NUMERIC' /&gt;
109 &lt;COLUMN NAME='UserId' EXPR='uid' DATATYPE='NUMERIC' /&gt;
110 &lt;COLUMN NAME='UserName' EXPR='name' /&gt;
111 &lt;/CHILD&gt;
112 &lt;/TEMPLATE&gt;
113 _EOT_
114 my $msg = new DBIx::XMLMessage ('TemplateString' =&gt; $tpl_str);
115 my $ghash = { 'OBJECT_ID' =&gt; [ 1, 2 ] };
116 my $dbh = DBI-&gt;connect('dbi:Sybase:server=x;database=master','sa','secret');
117 $msg-&gt;rexec ($dbh, $ghash);
118 </PRE>
119 </P>
120 <P>
121 <PRE> print &quot;\n\n&quot;, $msg-&gt;output_xml(0,0);
122 print &quot;\n\n&quot;, $msg-&gt;output_xml(0,1);
123 </PRE>
124 </P>
125 <P>
126 <HR>
127 <H2><A NAME="INBOUND_MESSAGE">INBOUND MESSAGE</A></H2>
128 <P>
129 <PRE> #!/usr/bin/perl
130 </PRE>
131 </P>
132 <P>
133 <PRE> use DBI;
134 use DBIx::XMLMessage;
135 </PRE>
136 </P>
137 <P>
138 <PRE> my $template_xml =&lt;&lt; &quot;_EOD1_&quot;;
139 &lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot; ?&gt;
140 &lt;TEMPLATE NAME='SysLogins' TYPE='XML' VERSION='1.0' TABLE='syslogins'
141 ACTION='SAVE'&gt;
142 &lt;KEY NAME='suid' DATATYPE='NUMERIC' PARENT_NAME='OBJECT_ID' /&gt;
143 &lt;COLUMN NAME='LoginId' EXPR='suid' DATATYPE='NUMERIC' /&gt;
144 &lt;COLUMN NAME='PasswordDate' EXPR='pwdate' DATATYPE='DATETIME'
145 BLTIN=&quot;fix_gmdatetime&quot; /&gt;
146 &lt;CHILD NAME='SysUsers' TABLE='sysusers'&gt;
147 &lt;KEY NAME='suid' PARENT_NAME='LoginId' DATATYPE='NUMERIC' /&gt;
148 &lt;COLUMN NAME='UserId' EXPR='uid' DATATYPE='NUMERIC' /&gt;
149 &lt;COLUMN NAME='UserName' EXPR='name' /&gt;
150 &lt;/CHILD&gt;
151 &lt;/TEMPLATE&gt;
152 _EOD1_
153 </PRE>
154 </P>
155 <P>
156 <PRE> my $message_xml =&lt;&lt; &quot;_EOD2_&quot;;
157 &lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
158 &lt;SysLogins&gt;
159 &lt;LoginId&gt;1&lt;/LoginId&gt;
160 &lt;PasswordDate&gt;1999/08/17 08:31&lt;/PasswordDate&gt;
161 &lt;SysUsers&gt;
162 &lt;UserId&gt;1&lt;/UserId&gt;
163 &lt;UserName&gt;sa&lt;/UserName&gt;
164 &lt;/SysUsers&gt;
165 &lt;/SysLogins&gt;
166 _EOD2_
167 </PRE>
168 </P>
169 <P>
170 <PRE> my $xmlmsg = new DBIx::XMLMessage ('TemplateString' =&gt; $template_xml);
171 my $msgtype = $xmlmsg-&gt;input_xml($message_xml);
172 my $ghash = {
173 'OBJECT_ID' =&gt; [ 1 ]
174 };
175 $xmlmsg-&gt;populate_objects ($ghash);
176 </PRE>
177 </P>
178 <P>
179 <PRE> my $dbh = DBI-&gt;connect('dbi:Sybase:server=x;database=master','sa','secret');
180 $xmlmsg-&gt;rexec ($dbh, $ghash);
181 print $xmlmsg-&gt;output_message();
182 </PRE>
183 </P>
184 <P>
185 <HR>
186 <H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
187 <P>
188 The package maintains simple XML templates that describe object structure.
189
190 </P>
191 <P>
192 The package is capable of generating SQL statements based on these
193 templates and executing them against DBI data sources. After executing the
194 SQL, the package formats the data results into XML strings. E.g. the
195 following simple template
196
197 </P>
198 <P>
199 <PRE> &lt;TEMPLATE NAME='SysLogins' TYPE='XML' VERSION='1.0' TABLE='syslogins'
200 ACTION='SAVE'&gt;
201 &lt;KEY NAME='suid' DATATYPE='NUMERIC' PARENT_NAME='OBJECT_ID' /&gt;
202 &lt;COLUMN NAME='LoginId' EXPR='suid' DATATYPE='NUMERIC' /&gt;
203 &lt;/TEMPLATE&gt;
204 </PRE>
205 </P>
206 <P>
207 being executed with key value = 1, will be tranlated into this SQL:
208
209 </P>
210 <P>
211 SELECT suid LoginId FROM syslogins where suid = 1
212
213 </P>
214 <P>
215 and the result will be formatted into this XML string:
216
217 </P>
218 <P>
219 <PRE> &lt;SysLogins&gt;
220 &lt;LoginId&gt;1&lt;LoginId&gt;
221 &lt;/SysLogins&gt;
222 </PRE>
223 </P>
224 <P>
225 Inbound messages can be processed according to the same kind of templates
226 and the database is updated accordingly. Templates are capable of defining
227 the SQL operators, plus new SAVE operation which is basically a combination
228 of SELECT and either INSERT or UPDATE depending on whether the record was
229 found by the compound key value or not.
230
231 </P>
232 <P>
233 <HR>
234 <H1><A NAME="SALES_PITCH">SALES PITCH</A></H1>
235 <P>
236 This package allows for objects exchange between different databases. They
237 could be from different vendors, as long as they both have DBD drivers. In
238 certain cases it is even possible to exchange objects between databases
239 with different data models. Publishing of databases on the web could
240 potentially be one of the applications as well.
241
242 </P>
243 <P>
244 <HR>
245 <H1><A NAME="TEMPLATE_TAGS">TEMPLATE TAGS</A></H1>
246 <P>
247 <HR>
248 <H2><A NAME="TEMPLATE">TEMPLATE</A></H2>
249 <P>
250 This is manadatory top-level tag. It can correspond to a certain table and
251 be processed just like table-level REFERENCE and CHILD attributes described
252 below. Some of TEMPLATE attributes are related to the whole template (e.g.
253 TYPE or VERSION) while others desribe the table ti's based on (e.g. TABLE)
254
255 </P>
256 <P>
257 If the TABLE attribute is defined, the generated SQL is going to run
258 against some table. Otherwise a SQL with no table will be generated. This
259 only makes sense for outbound messages and only possible on certain
260 engines, like Sybase. Also, the immediate child columns should contain
261 constants only for apparent reasons.
262
263 </P>
264 <P>
265 <HR>
266 <H2><A NAME="REFERENCE">REFERENCE</A></H2>
267 <P>
268 REFERENCE is a table-level tag. It's meant to represent a single record
269 from another table that's retrieved by unique key. E.g. if my current table
270 is EMPL then DEPARTMENT would be a REFERENCE since employee can have no
271 more than one departament.
272
273 </P>
274 <P>
275 <HR>
276 <H2><A NAME="CHILD">CHILD</A></H2>
277 <P>
278 This tag meant to represent a number of child records usually retrieved by
279 a foreign key value (probably primary key of the current table). Right now
280 there's no difference in processing between CHILD and REFERENCE, but it may
281 appear in the future releases.
282
283 </P>
284 <P>
285 <HR>
286 <H2><A NAME="COLUMN">COLUMN</A></H2>
287 <P>
288 This tag is pretty self-explanatory. Each COLUMN tag will appear on the
289 SELECT, INSERT or UPDATE list of the generated SQL.
290
291 </P>
292 <P>
293 <HR>
294 <H2><A NAME="KEY">KEY</A></H2>
295 <P>
296 Key represents linkage of this table's records to the parent table. All
297 KEY's will appear on the WHERE clause as AND components. This way of
298 linkage is typical for most of relational systems and considered to be a
299 good style. I guess it shouldn't be much of a restriction anyway. If it
300 gets that, you could try tweak up the WHERE_CLAUSE attribute..
301
302 </P>
303 <P>
304 <HR>
305 <H2><A NAME="PARAMETER">PARAMETER</A></H2>
306 <P>
307 This tag represents a parameter that will be passsed to a stored procedure.
308 Currently, only Sybase-style stored procedures are supported, i.e.
309
310 </P>
311 <P>
312 exec proc_name <CODE>@param_name</CODE> = 'param_value', ...
313
314 </P>
315 <P>
316 Fixes for Oracle, DB2 and Informix are welcome..
317
318 </P>
319 <P>
320 <HR>
321 <H1><A NAME="TEMPLATE_TAG_ATTRIBUTES">TEMPLATE TAG ATTRIBUTES</A></H1>
322 <P>
323 <HR>
324 <H2><A NAME="NAME">NAME</A></H2>
325 <P>
326 <PRE> Applicable to: All template tags
327 Required for: All template tags
328 </PRE>
329 </P>
330 <P>
331 NAME is the only required attribute for all of the template tags. The main
332 purpose of it is to specify the tag name as it will appear in the resulting
333 XML document. Also, depending on the template tag type (COLUMN, PARAMETER
334 and KEY) it may serve as default value for EXPR discussed below. Here's a
335 small example of how it works. If my column is represented in the template
336 like this:
337
338 </P>
339 <P>
340 <PRE> &lt;COLUMN NAME='ObjectId' /&gt;
341 </PRE>
342 </P>
343 <P>
344 the resulting SQL will contain
345
346 </P>
347 <P>
348 <PRE> SELECT ObjectID, ...
349 </PRE>
350 </P>
351 <P>
352 whereas if I have
353
354 </P>
355 <P>
356 <PRE> &lt;COLUMN NAME='ObjectId' EXPR='igObjectId' /&gt;
357 </PRE>
358 </P>
359 <P>
360 it will generate the following SQL:
361
362 </P>
363 <P>
364 <PRE> SELECT igObjectId ObjectID, ...
365 </PRE>
366 </P>
367 <P>
368 I.e. in the latter example, NAME used as an alias and EXPR as a real
369 database column name. The column in the first example has no alias.
370
371 </P>
372 <P>
373 <HR>
374 <H2><A NAME="ACTION">ACTION</A></H2>
375 <P>
376 <PRE> Applicable to: TEMPLATE, REFERENCE, CHILD
377 Required for: None
378 </PRE>
379 </P>
380 <P>
381 Possible values for this attibute are SELECT, INSERT, UPDATE, EXEC and
382 SAVE. If action is not provided, it is assumed that t he action should be
383 SELECT. The first 4 values correspond to SQL data management operators
384 (EXEC is vendor-specific and represents execution of a stored procedure).
385 The fifth value, SAVE, is basically a combination of SELECT and either
386 INSERT or UPDATE, depending on whether the record was found by the compound
387 key value or not. This often helps to avoid usage of complicated stored
388 procedures with primary key generation and keep things generic and
389 scalable. Primary key generation issue is addressed separately by using of
390 the GENERATE_PK attribute (see below).
391
392 </P>
393 <P>
394 <HR>
395 <H2><A NAME="BLTIN">BLTIN</A></H2>
396 <P>
397 <PRE> Applicable to: COLUMN
398 Required for: None
399 </PRE>
400 </P>
401 <P>
402 Represents a perl built-in function. before invocation of this subroutine
403 the package prepares array <CODE>@_</CODE> and makes it visible to the
404 built-in function. The 3 arguments received by the built-in are:
405 <CODE>$self</CODE> - DBIx::XMLMessage object <CODE>$node</CODE> -
406 Correspondent DBIx::XMLMessage::COLUMN object. You can use it to obtain
407 other column attributes, e.g. $node-&gt;{DATATYPE} <CODE>$value</CODE> -
408 The column value
409
410 </P>
411 <P>
412 Meaning of the value depends on direction of the message, i.e. whether the
413 message is inbound or outbound. In case of inbound message, this is the
414 value received by the package from outside world; if the message is inbound
415 then this is the value selected from database. There's one built-in
416 function that comes with the package -- fix_gmdatetime. It converts date
417 and time to GMT for outbound messages and from GMT to the database
418 date/time for inbound messages. Just add one attribute to your datetime
419 column:
420
421 </P>
422 <P>
423 <PRE> ... BLTIN=&quot;fix_gmdatetime&quot; ...
424 </PRE>
425 </P>
426 <P>
427 <HR>
428 <H2><A NAME="CARDINALITY">CARDINALITY</A></H2>
429 <P>
430 <PRE> Applicable to: KEY, PARAMETER, REFERENCE, CHILD
431 Required for: None
432 Possible values: REQUIRED, OPTIONAL
433 Default: REQUIRED
434 </PRE>
435 </P>
436 <P>
437 This parameter has different meaning for different element types. Optional
438 KEYs and PARAMETERs allow to proceed execution if the value for it was not
439 found at some point of execution. Optional CHILDs and REFERENCEs will be
440 skipped from execution, and hence from output, if the package failed to
441 collect all the key values.
442
443 </P>
444 <P>
445 <HR>
446 <H2><A NAME="DATATYPE">DATATYPE</A></H2>
447 <P>
448 <PRE> Applicable to: KEY, PARAMETER, COLUMN
449 Required for: None
450 Possible values: CHAR, VARCHAR, VARCHAR2, DATE, DATETIME, NUMERIC
451 Default: CHAR
452 </PRE>
453 </P>
454 <P>
455 This attribute loosely corresponds to the database column type. The only
456 processing difference in the core package is quoting of the non-numeric
457 datatypes, particularly those containign substrings CHAR, DATE or TIME. The
458 built-in fix_gmdatetime utilizes this attribute more extensively.
459
460 </P>
461 <P>
462 <HR>
463 <H2><A NAME="DEBUG">DEBUG</A></H2>
464 <P>
465 Recognized but not currently supported
466
467 </P>
468 <P>
469 <HR>
470 <H2><A NAME="DEFAULT">DEFAULT</A></H2>
471 <P>
472 <PRE> Applicable to: PARAMETER, COLUMN
473 Required for: None
474 Possible values: Any string or number
475 </PRE>
476 </P>
477 <P>
478 This attribute allows to provide a default value for COLUMNs and
479 PARAMETERS. Please note that default values are not being formatted, so
480 they have to represent the literal value. E.g. if you want to provide a
481 string DEFAULT it would look somewhat like this: ... DEFAULT =
482 ``'UNKNOWN'''
483
484 </P>
485 <P>
486 <HR>
487 <H2><A NAME="EXPR">EXPR</A></H2>
488 <P>
489 <PRE> Applicable to: All template tags
490 Required for: None
491 </PRE>
492 </P>
493 <P>
494 For COLUMN and KEY this attribute represents the actual database column
495 name or a constant. For PARAMETER
496
497 </P>
498 <P>
499 <HR>
500 <H2><A NAME="FACE">FACE</A></H2>
501 <P>
502 <PRE> Applicable to: COLUMN
503 Required for: None
504 Possible values: ATTRIBUTE, TAG
505 Default: TAG
506 </PRE>
507 </P>
508 <P>
509 This attribute allows to output certain columns as attributes, as opposed
510 to the default TAG-fasion output. Since it's not supported for inbound
511 messages yet, usage of this feature is not recommended.
512
513 </P>
514 <P>
515 <HR>
516 <H2><A NAME="GENERATE_PK">GENERATE_PK</A></H2>
517 <P>
518 <PRE> Applicable to: COLUMN
519 Required for: None
520 Possible values: HASH, SQL returning one value or name
521 </PRE>
522 </P>
523 <P>
524 This attribute allows you to specify how to generate primary key values.
525 You have 2 options here:
526
527 </P>
528 <P>
529 1. You can write your own Perl function, put its reference to the global
530 hash under the name of the table for which you intend to generate primary
531 key values and provide the value of 'HASH' as the GENERATE_PK value
532
533 </P>
534 <P>
535 2. You can put the generating SQL block/statement into the GENERATE_PK
536 value
537
538 </P>
539 <P>
540 <HR>
541 <H2><A NAME="HIDDEN">HIDDEN</A></H2>
542 <P>
543 <PRE> Applicable to: COLUMN
544 </PRE>
545 </P>
546 <P>
547 Indicates that the column will be excluded from the output. This attribute
548 only makes sense for outbound messages.
549
550 </P>
551 <P>
552 <HR>
553 <H2><A NAME="MAXROWS">MAXROWS</A></H2>
554 <P>
555 Currently not supported. In future, intends to limits the number of
556 selected rows.
557
558 </P>
559 <P>
560 <HR>
561 <H2><A NAME="PARENT_NAME">PARENT_NAME</A></H2>
562 <P>
563 <PRE> Applicable to: KEY
564 </PRE>
565 </P>
566 <P>
567 Indicates the name of the tag one level up to which this one tag is
568 corresponding. E.g.
569
570 </P>
571 <P>
572 <PRE> ...
573 &lt;COLUMN NAME='OBJECT_ID'/&gt;
574 &lt;REFERENCE ...&gt;
575 &lt;KEY NAME='nOrderId' PARENT_NAME='OBJECT_ID'/&gt;
576 &lt;/REFERENCE&gt;
577 </PRE>
578 </P>
579 <P>
580 This feature is a workaround allowing to have two columns descending from
581 the same parent column at the same level. There was some other prolem it
582 was helping to resolve, but I forgot what it was ;^)
583
584 </P>
585 <P>
586 <HR>
587 <H2><A NAME="PROC">PROC</A></H2>
588 <P>
589 <PRE> Applicable to: TEMPLATE, REFERENCE, CHILD
590 </PRE>
591 </P>
592 <P>
593 Used in conjunction with ACTION='PROC'. Defines the name of the stored
594 procedure to invoke.
595
596 </P>
597 <P>
598 <HR>
599 <H2><A NAME="RTRIMTEXT">RTRIMTEXT</A></H2>
600 <P>
601 Currently not supported. The package does automatic right-trimming for all
602 the character data.
603
604 </P>
605 <P>
606 <HR>
607 <H2><A NAME="TABLE">TABLE</A></H2>
608 <P>
609 Name of the table against which the SQL will be run.
610
611 </P>
612 <P>
613 <HR>
614 <H2><A NAME="TOLERANCE">TOLERANCE</A></H2>
615 <P>
616 <PRE> Applicable to: TEMPLATE, REFERENCE, CHILD
617 Possible values: IGNORE, CREATE, REJECT
618 Default: IGNORE
619 </PRE>
620 </P>
621 <P>
622 Allows to adjust package behaviour when SQL execution produces unexpected
623 result columns. E.g. if there's a stored procedure that will return the
624 results for your message, you can omit describing of all the resulting
625 COLUMNS in the template and instead specify ... TOLERANCE='CREATE' Whatever
626 columns are returned by the stored procedure (Sybase &amp; MS SQL) will be
627 added on-the-fly and available for the output.
628
629 </P>
630 <P>
631 <HR>
632 <H2><A NAME="WHERE_CLAUSE">WHERE_CLAUSE</A></H2>
633 <P>
634 Additional where clause. Added as an AND component at the end of generated
635 where clause.
636
637 </P>
638 <P>
639 <HR>
640 <H1><A NAME="METHODS">METHODS</A></H1>
641 <P>
642 <HR>
643 <H2><A NAME="new">new</A></H2>
644 <P>
645 <PRE> my $xmsg = new DBIx::XMLMessage (
646 [ _OnError =&gt; $err_coderef, ]
647 [ _OnTrace =&gt; $trace_coderef, ]
648 [ _OnDebug =&gt; $debug_coderef, ]
649 [ Handlers =&gt; $expat_handlers_hashref, ]
650 [ TemplateString =&gt; $xml_template_as_a_string, ]
651 [ TemplateFile =&gt; $xml_template_file_name, ]
652 )
653 </PRE>
654 </P>
655 <P>
656 You can specify either TemplateString or TemplateFile, but not both. If any
657 of those specified, the template will be parsed.
658
659 </P>
660 <P>
661 <HR>
662 <H2><A NAME="set_handlers">set_handlers</A></H2>
663 <P>
664 <PRE> $xmsg-&gt;set_handlers ($expat_handlers_hashref)
665 </PRE>
666 </P>
667 <P>
668 Set additional expat handlers, see XML::Parser::Expat. Normally you won't
669 use this. The only case I could think of is processing of encoding..
670
671 </P>
672 <P>
673 <HR>
674 <H2><A NAME="prepare_template">prepare_template</A></H2>
675 <P>
676 <PRE> $xmsg-&gt;prepare_template ($template_xml_string)
677 </PRE>
678 </P>
679 <P>
680 This method can be invoked if the template was not specified in the 'new'
681 method invocation.
682
683 </P>
684 <P>
685 <HR>
686 <H2><A NAME="prepare_template_from_file">prepare_template_from_file</A></H2>
687 <P>
688 <PRE> $xmsg-&gt;prepare_template_from_file ($template_file_name)
689 </PRE>
690 </P>
691 <P>
692 Same as above, but template is read from file here.
693
694 </P>
695 <P>
696 <HR>
697 <H2><A NAME="input_xml">input_xml</A></H2>
698 <P>
699 <PRE> $xmsg-&gt;input_xml ($inbound_xml_message_content)
700 </PRE>
701 </P>
702 <P>
703 Parse an inbound XML message. The values form this message will be used to
704 fill in COLUMNS and PARAMETERS. The structure of this message should comply
705 with template. Uses Tree parsing style.
706
707 </P>
708 <P>
709 <HR>
710 <H2><A NAME="input_xml_file">input_xml_file</A></H2>
711 <P>
712 <PRE> $xmsg-&gt;input_xml_file ($inbound_xml_message_file_name)
713 </PRE>
714 </P>
715 <P>
716 Same as above, but the XML message is read from a file.
717
718 </P>
719 <P>
720 <HR>
721 <H2><A NAME="populate_objects">populate_objects</A></H2>
722 <P>
723 <PRE> $xmsg-&gt;populate_objects ($global_hash_ref [, $matching_object
724 [, $tag_name [, $tag_content, [$parameter_index]]]])
725 </PRE>
726 </P>
727 <P>
728 This method is trying to stuff the existing template with the inbound
729 message previously parsed by one of the 'input_xml' methods. The only
730 mandatory attribute is global hash reference, which has to contain key
731 values for the topmost tag TEMPLATE.
732
733 </P>
734 <P>
735 <HR>
736 <H2><A NAME="rexec">rexec</A></H2>
737 <P>
738 <PRE> $xmsg-&gt;rexec ($dbh, $global_hash_ref)
739 </PRE>
740 </P>
741 <P>
742 This method is running the created query against a DBI/DBD source and fills
743 in the template with results in order to make them available for subsequent
744 output_message call. In case of INSERT/UPDATE operations only key values
745 will be filled in.
746
747 </P>
748 <P>
749 <HR>
750 <H2><A NAME="output_message">output_message</A></H2>
751 <P>
752 This method returns a string with query results in XML format suitable for
753 printing or whatever manupulations seem appropriate.
754
755 </P>
756 <P>
757 <HR>
758 <H1><A NAME="SEE_ALSO">SEE ALSO</A></H1>
759 <P>
760 <PRE> XML::Parser
761 XML::Parser::Expat
762 </PRE>
763 </P>
764 <P>
765 <HR>
766 <H1><A NAME="AUTHORS">AUTHORS</A></H1>
767 <P>
768 <PRE> Andrei Nossov &lt;[email protected]&gt;
769 </PRE>
770 </P>
771 <P>
772 This library is free software; you can redistribute it and/or modify it
773 under the same terms as Perl itself.
774
775 </P>
776
777 </BODY>
778
779 </HTML>