.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
. if \nF \{
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "XMLMessage 3pm"
.TH XMLMessage 3pm "2001-09-08" "perl v5.18.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DBIx::XMLMessage \- XML Message exchange between DBI data sources
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.SS "\s-1OUTBOUND MESSAGE\s0"
.IX Subsection "OUTBOUND MESSAGE"
.Vb 1
\& #!/usr/bin/perl
\&
\& use DBI;
\& use DBIx::XMLMessage;
\&
\& # Template string
\& my $tpl_str =<< "_EOT_";
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
\& _EOT_
\& my $msg = new DBIx::XMLMessage (\*(AqTemplateString\*(Aq => $tpl_str);
\& my $ghash = { \*(AqOBJECT_ID\*(Aq => [ 1, 2 ] };
\& my $dbh = DBI\->connect(\*(Aqdbi:Sybase:server=x;database=master\*(Aq,\*(Aqsa\*(Aq,\*(Aqsecret\*(Aq);
\& $msg\->rexec ($dbh, $ghash);
\&
\& print "\en\en", $msg\->output_xml(0,0);
\& print "\en\en", $msg\->output_xml(0,1);
.Ve
.SS "\s-1INBOUND MESSAGE\s0"
.IX Subsection "INBOUND MESSAGE"
.Vb 1
\& #!/usr/bin/perl
\&
\& use DBI;
\& use DBIx::XMLMessage;
\&
\& my $template_xml =<< "_EOD1_";
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
\& _EOD1_
\&
\& my $message_xml =<< "_EOD2_";
\&
\&
\& 1
\& 1999/08/17 08:31
\&
\& 1
\& sa
\&
\&
\& _EOD2_
\&
\& my $xmlmsg = new DBIx::XMLMessage (\*(AqTemplateString\*(Aq => $template_xml);
\& my $msgtype = $xmlmsg\->input_xml($message_xml);
\& my $ghash = {
\& \*(AqOBJECT_ID\*(Aq => [ 1 ]
\& };
\& $xmlmsg\->populate_objects ($ghash);
\&
\& my $dbh = DBI\->connect(\*(Aqdbi:Sybase:server=x;database=master\*(Aq,\*(Aqsa\*(Aq,\*(Aqsecret\*(Aq);
\& $xmlmsg\->rexec ($dbh, $ghash);
\& print $xmlmsg\->output_message();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The package maintains simple \s-1XML\s0 templates that describe object structure.
.PP
The package is capable of generating \s-1SQL\s0 statements based on these templates
and executing them against \s-1DBI\s0 data sources. After executing the \s-1SQL,\s0 the
package formats the data results into \s-1XML\s0 strings. E.g. the following simple
template
.PP
.Vb 5
\&
\&
\&
\&
.Ve
.PP
being executed with key value = 1, will be tranlated into this \s-1SQL:\s0
.PP
\&\s-1SELECT\s0 suid LoginId \s-1FROM\s0 syslogins where suid = 1
.PP
and the result will be formatted into this \s-1XML\s0 string:
.PP
.Vb 3
\&
\& 1
\&
.Ve
.PP
Inbound messages can be processed according to the same kind of templates
and the database is updated accordingly. Templates are capable of defining
the \s-1SQL\s0 operators, plus new \s-1SAVE\s0 operation which is basically a combination
of \s-1SELECT\s0 and either \s-1INSERT\s0 or \s-1UPDATE\s0 depending on whether the record was
found by the compound key value or not.
.SH "SALES PITCH"
.IX Header "SALES PITCH"
This package allows for objects exchange between different databases. They
could be from different vendors, as long as they both have \s-1DBD\s0 drivers. In
certain cases it is even possible to exchange objects between databases with
different data models. Publishing of databases on the web could
potentially be one of the applications as well.
.SH "TEMPLATE TAGS"
.IX Header "TEMPLATE TAGS"
.SS "\s-1TEMPLATE\s0"
.IX Subsection "TEMPLATE"
This is manadatory top-level tag. It can correspond to a certain table and
be processed just like table-level \s-1REFERENCE\s0 and \s-1CHILD\s0 attributes described
below. Some of \s-1TEMPLATE\s0 attributes are related to the whole template (e.g.
\&\s-1TYPE\s0 or \s-1VERSION\s0) while others desribe the table ti's based on (e.g. \s-1TABLE\s0)
.PP
If the \s-1TABLE\s0 attribute is defined, the generated \s-1SQL\s0 is going to run against
some table. Otherwise a \s-1SQL\s0 with no table will be generated. This only makes
sense for outbound messages and only possible on certain engines, like
Sybase. Also, the immediate child columns should contain constants only for
apparent reasons.
.SS "\s-1REFERENCE\s0"
.IX Subsection "REFERENCE"
\&\s-1REFERENCE\s0 is a table-level tag. It's meant to represent a single record from
another table that's retrieved by unique key. E.g. if my current table is
\&\s-1EMPL\s0 then \s-1DEPARTMENT\s0 would be a \s-1REFERENCE\s0 since employee can have no more
than one departament.
.SS "\s-1CHILD\s0"
.IX Subsection "CHILD"
This tag meant to represent a number of child records usually retrieved by
a foreign key value (probably primary key of the current table). Right now
there's no difference in processing between \s-1CHILD\s0 and \s-1REFERENCE,\s0 but it may
appear in the future releases.
.SS "\s-1COLUMN\s0"
.IX Subsection "COLUMN"
This tag is pretty self-explanatory. Each \s-1COLUMN\s0 tag will appear on the
\&\s-1SELECT, INSERT\s0 or \s-1UPDATE\s0 list of the generated \s-1SQL.\s0
.SS "\s-1KEY\s0"
.IX Subsection "KEY"
Key represents linkage of this table's records to the parent table. All
\&\s-1KEY\s0's will appear on the \s-1WHERE\s0 clause as \s-1AND\s0 components. This way of linkage
is typical for most of relational systems and considered to be a good style.
I guess it shouldn't be much of a restriction anyway. If it gets that, you
could try tweak up the \s-1WHERE_CLAUSE\s0 attribute..
.SS "\s-1PARAMETER\s0"
.IX Subsection "PARAMETER"
This tag represents a parameter that will be passsed to a stored procedure.
Currently, only Sybase-style stored procedures are supported, i.e.
.PP
exec proc_name \f(CW@param_name\fR = 'param_value', ...
.PP
Fixes for Oracle, \s-1DB2\s0 and Informix are welcome..
.SH "TEMPLATE TAG ATTRIBUTES"
.IX Header "TEMPLATE TAG ATTRIBUTES"
.SS "\s-1NAME\s0"
.IX Subsection "NAME"
.Vb 2
\& Applicable to: All template tags
\& Required for: All template tags
.Ve
.PP
\&\s-1NAME\s0 is the only required attribute for all of the template tags. The main
purpose of it is to specify the tag name as it will appear in the resulting
\&\s-1XML\s0 document. Also, depending on the template tag type (\s-1COLUMN, PARAMETER\s0
and \s-1KEY\s0) it may serve as default value for \s-1EXPR\s0 discussed below. Here's a
small example of how it works. If my column is represented in the template
like this:
.PP
.Vb 1
\&
.Ve
.PP
the resulting \s-1SQL\s0 will contain
.PP
.Vb 1
\& SELECT ObjectID, ...
.Ve
.PP
whereas if I have
.PP
.Vb 1
\&
.Ve
.PP
it will generate the following \s-1SQL:\s0
.PP
.Vb 1
\& SELECT igObjectId ObjectID, ...
.Ve
.PP
I.e. in the latter example, \s-1NAME\s0 used as an alias and \s-1EXPR\s0 as a real
database column name. The column in the first example has no alias.
.SS "\s-1ACTION\s0"
.IX Subsection "ACTION"
.Vb 2
\& Applicable to: TEMPLATE, REFERENCE, CHILD
\& Required for: None
.Ve
.PP
Possible values for this attibute are \s-1SELECT, INSERT, UPDATE, EXEC\s0 and \s-1SAVE.\s0
If action is not provided, it is assumed that t he action should be \s-1SELECT.\s0
The first 4 values correspond to \s-1SQL\s0 data management operators (\s-1EXEC\s0 is
vendor-specific and represents execution of a stored procedure). The fifth
value, \s-1SAVE,\s0 is basically a combination of \s-1SELECT\s0 and either \s-1INSERT\s0 or
\&\s-1UPDATE,\s0 depending on whether the record was found by the compound key value
or not. This often helps to avoid usage of complicated stored procedures
with primary key generation and keep things generic and scalable. Primary
key generation issue is addressed separately by using of the \s-1GENERATE_PK\s0
attribute (see below).
.SS "\s-1BLTIN\s0"
.IX Subsection "BLTIN"
.Vb 2
\& Applicable to: COLUMN
\& Required for: None
.Ve
.PP
Represents a perl built-in function. before invocation of this subroutine
the package prepares array \f(CW@_\fR and makes it visible to the built-in function.
The 3 arguments received by the built-in are:
\f(CW$self\fR \- DBIx::XMLMessage object
\f(CW$node\fR \- Correspondent DBIx::XMLMessage::COLUMN object. You
can use it to obtain other column attributes, e.g.
\f(CW$node\fR\->{\s-1DATATYPE\s0}
\f(CW$value\fR \- The column value
.PP
Meaning of the value depends on direction of the message, i.e. whether the
message is inbound or outbound. In case of inbound message, this is the
value received by the package from outside world; if the message is inbound
then this is the value selected from database. There's one built-in function
that comes with the package \*(-- fix_gmdatetime. It converts date and time to
\&\s-1GMT\s0 for outbound messages and from \s-1GMT\s0 to the database date/time for inbound
messages. Just add one attribute to your datetime column:
.PP
.Vb 1
\& ... BLTIN="fix_gmdatetime" ...
.Ve
.SS "\s-1CARDINALITY\s0"
.IX Subsection "CARDINALITY"
.Vb 4
\& Applicable to: KEY, PARAMETER, REFERENCE, CHILD
\& Required for: None
\& Possible values: REQUIRED, OPTIONAL
\& Default: REQUIRED
.Ve
.PP
This parameter has different meaning for different element types. Optional
KEYs and PARAMETERs allow to proceed execution if the value for it was not
found at some point of execution. Optional CHILDs and REFERENCEs will be
skipped from execution, and hence from output, if the package failed to
collect all the key values.
.SS "\s-1DATATYPE\s0"
.IX Subsection "DATATYPE"
.Vb 4
\& Applicable to: KEY, PARAMETER, COLUMN
\& Required for: None
\& Possible values: CHAR, VARCHAR, VARCHAR2, DATE, DATETIME, NUMERIC
\& Default: CHAR
.Ve
.PP
This attribute loosely corresponds to the database column type. The only
processing difference in the core package is quoting of the non-numeric
datatypes, particularly those containign substrings \s-1CHAR, DATE\s0 or \s-1TIME.\s0
The built-in fix_gmdatetime utilizes this attribute more extensively.
.SS "\s-1DEBUG\s0"
.IX Subsection "DEBUG"
Recognized but not currently supported
.SS "\s-1DEFAULT\s0"
.IX Subsection "DEFAULT"
.Vb 3
\& Applicable to: PARAMETER, COLUMN
\& Required for: None
\& Possible values: Any string or number
.Ve
.PP
This attribute allows to provide a default value for COLUMNs and \s-1PARAMETERS.\s0
Please note that default values are not being formatted, so they have to
represent the literal value. E.g. if you want to provide a string \s-1DEFAULT\s0
it would look somewhat like this:
... \s-1DEFAULT\s0 = \*(L"'\s-1UNKNOWN\s0'\*(R"
.SS "\s-1EXPR\s0"
.IX Subsection "EXPR"
.Vb 2
\& Applicable to: All template tags
\& Required for: None
.Ve
.PP
For \s-1COLUMN\s0 and \s-1KEY\s0 this attribute represents the actual database column name
or a constant. For \s-1PARAMETER\s0
.SS "\s-1FACE\s0"
.IX Subsection "FACE"
.Vb 4
\& Applicable to: COLUMN
\& Required for: None
\& Possible values: ATTRIBUTE, TAG
\& Default: TAG
.Ve
.PP
This attribute allows to output certain columns as attributes, as opposed
to the default TAG-fasion output. Since it's not supported for inbound
messages yet, usage of this feature is not recommended.
.SS "\s-1GENERATE_PK\s0"
.IX Subsection "GENERATE_PK"
.Vb 3
\& Applicable to: COLUMN
\& Required for: None
\& Possible values: HASH, SQL returning one value or name
.Ve
.PP
This attribute allows you to specify how to generate primary key values. You
have 2 options here:
.PP
1. You can write your own Perl function, put its reference to the global
hash under the name of the table for which you intend to generate primary
key values and provide the value of '\s-1HASH\s0' as the \s-1GENERATE_PK\s0 value
.PP
2. You can put the generating \s-1SQL\s0 block/statement into the \s-1GENERATE_PK\s0 value
.SS "\s-1HIDDEN\s0"
.IX Subsection "HIDDEN"
.Vb 1
\& Applicable to: COLUMN
.Ve
.PP
Indicates that the column will be excluded from the output. This attribute
only makes sense for outbound messages.
.SS "\s-1MAXROWS\s0"
.IX Subsection "MAXROWS"
Currently not supported. In future, intends to limits the number of selected
rows.
.SS "\s-1PARENT_NAME\s0"
.IX Subsection "PARENT_NAME"
.Vb 1
\& Applicable to: KEY
.Ve
.PP
Indicates the name of the tag one level up to which this one tag is
corresponding. E.g.
.PP
.Vb 5
\& ...
\&
\&
\&
\&
.Ve
.PP
This feature is a workaround allowing to have two columns descending from
the same parent column at the same level. There was some other prolem it
was helping to resolve, but I forgot what it was ;^)
.SS "\s-1PROC\s0"
.IX Subsection "PROC"
.Vb 1
\& Applicable to: TEMPLATE, REFERENCE, CHILD
.Ve
.PP
Used in conjunction with ACTION='\s-1PROC\s0'. Defines the name of the stored
procedure to invoke.
.SS "\s-1RTRIMTEXT\s0"
.IX Subsection "RTRIMTEXT"
Currently not supported. The package does automatic right-trimming for all
the character data.
.SS "\s-1TABLE\s0"
.IX Subsection "TABLE"
Name of the table against which the \s-1SQL\s0 will be run.
.SS "\s-1TOLERANCE\s0"
.IX Subsection "TOLERANCE"
.Vb 3
\& Applicable to: TEMPLATE, REFERENCE, CHILD
\& Possible values: IGNORE, CREATE, REJECT
\& Default: IGNORE
.Ve
.PP
Allows to adjust package behaviour when \s-1SQL\s0 execution produces unexpected
result columns. E.g. if there's a stored procedure that will return the
results for your message, you can omit describing of all the resulting
\&\s-1COLUMNS\s0 in the template and instead specify
... TOLERANCE='\s-1CREATE\s0'
Whatever columns are returned by the stored procedure (Sybase & \s-1MS SQL\s0) will
be added on-the-fly and available for the output.
.SS "\s-1WHERE_CLAUSE\s0"
.IX Subsection "WHERE_CLAUSE"
Additional where clause. Added as an \s-1AND\s0 component at the end of generated
where clause.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
.Vb 7
\& my $xmsg = new DBIx::XMLMessage (
\& [ _OnError => $err_coderef, ]
\& [ _OnTrace => $trace_coderef, ]
\& [ Handlers => $expat_handlers_hashref, ]
\& [ TemplateString => $xml_template_as_a_string, ]
\& [ TemplateFile => $xml_template_file_name, ]
\& )
.Ve
.PP
You can specify either TemplateString or TemplateFile, but not both. If any
of those specified, the template will be parsed.
.SS "set_handlers"
.IX Subsection "set_handlers"
.Vb 1
\& $xmsg\->set_handlers ($expat_handlers_hashref)
.Ve
.PP
Set additional expat handlers, see XML::Parser::Expat. Normally you won't
use this. The only case I could think of is processing of encoding..
.SS "prepare_template"
.IX Subsection "prepare_template"
.Vb 1
\& $xmsg\->prepare_template ($template_xml_string)
.Ve
.PP
This method can be invoked if the template was not specified in the 'new'
method invocation.
.SS "prepare_template_from_file"
.IX Subsection "prepare_template_from_file"
.Vb 1
\& $xmsg\->prepare_template_from_file ($template_file_name)
.Ve
.PP
Same as above, but template is read from file here.
.SS "input_xml"
.IX Subsection "input_xml"
.Vb 1
\& $xmsg\->input_xml ($inbound_xml_message_content)
.Ve
.PP
Parse an inbound \s-1XML\s0 message. The values form this message will be used to
fill in \s-1COLUMNS\s0 and \s-1PARAMETERS.\s0 The structure of this message should comply
with template. Uses Tree parsing style.
.SS "input_xml_file"
.IX Subsection "input_xml_file"
.Vb 1
\& $xmsg\->input_xml_file ($inbound_xml_message_file_name)
.Ve
.PP
Same as above, but the \s-1XML\s0 message is read from a file.
.SS "populate_objects"
.IX Subsection "populate_objects"
.Vb 2
\& $xmsg\->populate_objects ($global_hash_ref [, $matching_object
\& [, $tag_name [, $tag_content, [$parameter_index]]]])
.Ve
.PP
This method is trying to stuff the existing template with the inbound
message previously parsed by one of the 'input_xml' methods. The only
mandatory attribute is global hash reference, which has to contain key
values for the topmost tag \s-1TEMPLATE.\s0
.SS "rexec"
.IX Subsection "rexec"
.Vb 1
\& $xmsg\->rexec ($dbh, $global_hash_ref)
.Ve
.PP
This method is running the created query against a \s-1DBI/DBD\s0 source and fills
in the template with results in order to make them available for subsequent
output_message call. In case of \s-1INSERT/UPDATE\s0 operations only key values
will be filled in.
.SS "output_message"
.IX Subsection "output_message"
This method returns a string with query results in \s-1XML\s0 format suitable for
printing or whatever manupulations seem appropriate.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.Vb 2
\& XML::Parser
\& XML::Parser::Expat
.Ve
.SH "AUTHORS"
.IX Header "AUTHORS"
.Vb 1
\& Andrei Nossov
.Ve
.PP
This library is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.