XMLMessage(3pm)

NAME 💖

okay so bestie, welcome to XMLMessage(3pm) from the User Contributed Perl Documentation. This is DBIx::XMLMessage — XML Message exchange between DBI data sources. no cap, that's the whole vibe. periodt. 💅✨

SYNOPSIS ✨

OUTBOUND MESSAGE 🦋

here's the outbound message main character moment, copy-paste exact bestie:

#!/usr/bin/perl

use DBI;
use DBIx::XMLMessage;

# Template string
my $tpl_str =<< "_EOT_";
<?xml version="1.0" encoding="UTF-8" ?>
<TEMPLATE NAME='SysLogins' TYPE='XML' VERSION='1.0' TABLE='syslogins'>
<KEY NAME='suid' DATATYPE='NUMERIC' PARENT_NAME='OBJECT_ID' />
<COLUMN NAME='LoginId' EXPR='suid' DATATYPE='NUMERIC' />
<COLUMN NAME='PasswordDate' EXPR='pwdate' DATATYPE='DATETIME'
    BLTIN="fix_gmdatetime" />
<CHILD NAME='SysUsers' TABLE='sysusers'>
    <KEY NAME='suid' PARENT_NAME='LoginId' DATATYPE='NUMERIC' />
    <COLUMN NAME='UserId' EXPR='uid' DATATYPE='NUMERIC' />
    <COLUMN NAME='UserName' EXPR='name' />
</CHILD>
</TEMPLATE>
_EOT_
my $msg = new DBIx::XMLMessage ('TemplateString' => $tpl_str);
my $ghash = { 'OBJECT_ID' => [ 1, 2 ] };
my $dbh = DBI->connect('dbi:Sybase:server=x;database=master','sa','secret');
$msg->rexec ($dbh, $ghash);

print "\n\n", $msg->output_xml(0,0);
print "\n\n", $msg->output_xml(0,1);

INBOUND MESSAGE 🎀

and now the inbound message, it's giving reverse flow:

#!/usr/bin/perl

use DBI;
use DBIx::XMLMessage;

my $template_xml =<< "_EOD1_";
<?xml version="1.0" encoding="UTF-8" ?>
<TEMPLATE NAME='SysLogins' TYPE='XML' VERSION='1.0' TABLE='syslogins'
    ACTION='SAVE'>
<KEY NAME='suid' DATATYPE='NUMERIC' PARENT_NAME='OBJECT_ID' />
<COLUMN NAME='LoginId' EXPR='suid' DATATYPE='NUMERIC' />
<COLUMN NAME='PasswordDate' EXPR='pwdate' DATATYPE='DATETIME'
    BLTIN="fix_gmdatetime" />
<CHILD NAME='SysUsers' TABLE='sysusers'>
    <KEY NAME='suid' PARENT_NAME='LoginId' DATATYPE='NUMERIC' />
    <COLUMN NAME='UserId' EXPR='uid' DATATYPE='NUMERIC' />
    <COLUMN NAME='UserName' EXPR='name' />
</CHILD>
</TEMPLATE>
_EOD1_

my $message_xml =<< "_EOD2_";
<?xml version="1.0" encoding="UTF-8"?>
<SysLogins>
<LoginId>1</LoginId>
<PasswordDate>1999/08/17 08:31</PasswordDate>
<SysUsers>
    <UserId>1</UserId>
    <UserName>sa</UserName>
</SysUsers>
</SysLogins>
_EOD2_

my $xmlmsg = new DBIx::XMLMessage ('TemplateString' => $template_xml);
my $msgtype = $xmlmsg->input_xml($message_xml);
my $ghash = {
    'OBJECT_ID' => [ 1 ]
};
$xmlmsg->populate_objects ($ghash);

my $dbh = DBI->connect('dbi:Sybase:server=x;database=master','sa','secret');
$xmlmsg->rexec ($dbh, $ghash);
print $xmlmsg->output_message();

DESCRIPTION 💅

The package maintains simple XML templates that describe object structure. lowkey iconic.

The package is capable of generating SQL statements based on these templates and executing them against DBI data sources. After executing the SQL, the package formats the data results into XML strings. E.g. the following simple template

<TEMPLATE NAME='SysLogins' TYPE='XML' VERSION='1.0' TABLE='syslogins'
    ACTION='SAVE'>
<KEY NAME='suid' DATATYPE='NUMERIC' PARENT_NAME='OBJECT_ID' />
<COLUMN NAME='LoginId' EXPR='suid' DATATYPE='NUMERIC' />
</TEMPLATE>

being executed with key value = 1, will be translated into this SQL:

SELECT suid LoginId FROM syslogins where suid = 1

and the result will be formatted into this XML string:

<SysLogins>
    <LoginId>1<LoginId>
</SysLogins>

Inbound messages can be processed according to the same kind of templates and the database is updated accordingly. Templates are capable of defining the SQL operators, plus new SAVE operation which is basically a combination of SELECT and either INSERT or UPDATE depending on whether the record was found by the compound key value or not. slay. 🔥

SALES PITCH 🌈

This package allows for objects exchange between different databases. They could be from different vendors, as long as they both have DBD 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. it's giving interoperability, bestie. 🫶

TEMPLATE TAGS 🧚

okay bestie, these are the tags that make the whole thing go. 💖

TEMPLATE 👑

This is mandatory top-level tag. It can correspond to a certain table and be processed just like table-level REFERENCE and CHILD attributes described below. Some of TEMPLATE attributes are related to the whole template (e.g. TYPE or VERSION) while others describe the table it's based on (e.g. TABLE).

If the TABLE attribute is defined, the generated SQL is going to run against some table. Otherwise a SQL 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. iykyk.

REFERENCE 🦋

REFERENCE 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 EMPL then DEPARTMENT would be a REFERENCE since employee can have no more than one department. one record, one vibe.

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 CHILD and REFERENCE, but it may appear in the future releases. fr fr, future updates might change that.

COLUMN 🌸

This tag is pretty self-explanatory. Each COLUMN tag will appear on the SELECT, INSERT or UPDATE list of the generated SQL. it's giving column energy.

KEY 🔑

Key represents linkage of this table's records to the parent table. All KEY's will appear on the WHERE clause as AND 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 WHERE_CLAUSE attribute.. no cap.

PARAMETER 💜

This tag represents a parameter that will be passed to a stored procedure. Currently, only Sybase-style stored procedures are supported, i.e.

exec proc_name @param_name = 'param_value', ...

Fixes for Oracle, DB2 and Informix are welcome.. bestie if you got those, send them in. 🫶

✨ TEMPLATE TAG ATTRIBUTES ✨

okay so now we're getting into the ~attributes~ that make these template tags do their little dances. each one has its own rules, so let's go one by one. no skipping, bestie! 💅

NAME

Applicable to: All template tags Required for: All template tags

NAME is literally the only required attribute for every single template tag. its main character job? to specify the tag name as it will appear in the resulting XML document. also, depending on the template tag type (COLUMN, PARAMETER and KEY) it may serve as the default value for EXPR (which we'll get to below). here's a tiny example of how it works: if my column is represented in the template like this:

<COLUMN NAME='ObjectId' />

the resulting SQL will contain:

SELECT ObjectID, ...

whereas if I have:

<COLUMN NAME='ObjectId' EXPR='igObjectId' />

it will generate the following SQL:

SELECT igObjectId ObjectID, ...

I.e. in the latter example, NAME is used as an alias and EXPR as the real database column name. the column in the first example has no alias. periodt. 💖

ACTION

Applicable to: TEMPLATE, REFERENCE, CHILD Required for: None

possible values for this attribute are SELECT, INSERT, UPDATE, EXEC and SAVE. if action is not provided, it's assumed that the action should be SELECT. the first 4 values correspond to SQL data management operators (EXEC is vendor-specific and represents execution of a stored procedure). the fifth value, SAVE, is basically a combination of SELECT and either INSERT or UPDATE, 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 keeps things generic and scalable. the primary key generation issue is addressed separately by using the GENERATE_PK attribute (see below). slay. ✨

BLTIN

Applicable to: COLUMN Required for: None

represents a perl built-in function. before invocation of this subroutine, the package prepares array @_ and makes it visible to the built-in function. the 3 arguments received by the built-in are:

• $self — DBIx::XMLMessage object
• $node — Correspondent DBIx::XMLMessage::COLUMN object. you can use it to obtain other column attributes, e.g. $node->{DATATYPE}
• $value — The column value

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. (yes, the original says "inbound" twice, but we know what's up 😭). there's one built-in function that comes with the package — fix_gmdatetime. it converts date and time to GMT for outbound messages and from GMT to the database date/time for inbound messages. just add one attribute to your datetime column:

... BLTIN="fix_gmdatetime" ...

CARDINALITY

Applicable to: KEY, PARAMETER, REFERENCE, CHILD Required for: None Possible values: REQUIRED, OPTIONAL Default: REQUIRED

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. it's giving flexible. 💅

DATATYPE

Applicable to: KEY, PARAMETER, COLUMN Required for: None Possible values: CHAR, VARCHAR, VARCHAR2, DATE, DATETIME, NUMERIC Default: CHAR

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 containing substrings CHAR, DATE or TIME. the built-in fix_gmdatetime utilizes this attribute more extensively. so if you're doing date stuff, pay attention bestie. 🗓️

DEBUG

Recognized but not currently supported. (it's just a vibe, okay? not yet functional. 🙈)

DEFAULT

Applicable to: PARAMETER, COLUMN Required for: None Possible values: Any string or number

this attribute allows to provide a default value for COLUMNs and PARAMETERs. 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 DEFAULT it would look somewhat like this:

... DEFAULT = "'UNKNOWN'"

so don't forget the inner quotes, okay? 💖

EXPR

Applicable to: All template tags Required for: None

for COLUMN and KEY this attribute represents the actual database column name or a constant. for PARAMETER

(and then the original just... stops? 😭 that's literally how it ends. iconic.)

FACE

Applicable to: COLUMN Required for: None Possible values: ATTRIBUTE, TAG Default: TAG

this attribute allows to output certain columns as attributes, as opposed to the default TAG-style output. since it's not supported for inbound messages yet, usage of this feature is not recommended. so like, proceed with caution. ⚠️

GENERATE_PK

Applicable to: COLUMN Required for: None Possible values: HASH, SQL returning one value or name

this attribute allows you to specify how to generate primary key values. you have 2 options here:

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 'HASH' as the GENERATE_PK value
2. you can put the generating SQL block/statement into the GENERATE_PK value

so either go custom Perl or go SQL. your choice, bestie. 🔑

HIDDEN

Applicable to: COLUMN

indicates that the column will be excluded from the output. this attribute only makes sense for outbound messages. so if you're like "not me, not today", this is your friend. 🙈

MAXROWS

Currently not supported. in future, intends to limit the number of selected rows. (future vibe, not yet. ⏳)

PARENT_NAME

Applicable to: KEY

indicates the name of the tag one level up to which this one tag is corresponding. e.g.

...
<COLUMN NAME='OBJECT_ID'/>
<REFERENCE ...>
    <KEY NAME='nOrderId' PARENT_NAME='OBJECT_ID'/>
</REFERENCE>

this feature is a workaround allowing to have two columns descending from the same parent column at the same level. there was some other problem it was helping to resolve, but I forgot what it was ;^) (same, honestly. 😂)

PROC

Applicable to: TEMPLATE, REFERENCE, CHILD

used in conjunction with ACTION='PROC'. defines the name of the stored procedure to invoke. so if you're calling a stored proc, this is where you put its name. 🏷️

RTRIMTEXT

Currently not supported. the package does automatic right-trimming for all the character data. so like, it's already happening, no need for this. ✂️

TABLE

Name of the table against which the SQL will be run. simple as that. 🗄️

TOLERANCE

Applicable to: TEMPLATE, REFERENCE, CHILD Possible values: IGNORE, CREATE, REJECT Default: IGNORE

allows to adjust package behaviour when SQL 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 COLUMNs in the template and instead specify:

... TOLERANCE='CREATE'

whatever columns are returned by the stored procedure (Sybase & MS SQL) will be added on-the-fly and available for the output. so it's like magic, but for SQL. ✨

WHERE_CLAUSE

Additional where clause. added as an AND component at the end of generated where clause. so it's like a little extra filter, you know? 🔍

---

✨ METHODS ✨

now we're getting into the methods, bestie. these are the functions you can call on your DBIx::XMLMessage object. let's go! 💅

new

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, ]
)

you can specify either TemplateString or TemplateFile, but not both. if any of those specified, the template will be parsed. so pick your fighter. 🥊

set_handlers

$xmsg->set_handlers ($expat_handlers_hashref)

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.. (so like, niche but important if you need it. 🌐)

prepare_template

$xmsg->prepare_template ($template_xml_string)

this method can be invoked if the template was not specified in the new method invocation. so if you forgot to set it earlier, here's your chance. 📝

prepare_template_from_file

$xmsg->prepare_template_from_file ($template_file_name)

same as above, but template is read from file here. so if your template is chillin' in a file, use this. 📂

input_xml

$xmsg->input_xml ($inbound_xml_message_content)

parse an inbound XML message. the values from this message will be used to fill in COLUMNs and PARAMETERs. the structure of this message should comply with template. uses Tree parsing style. so it's like reading the message and making it fit your template. 🌳

input_xml_file

$xmsg->input_xml_file ($inbound_xml_message_file_name)

same as above, but the XML message is read from a file. so if you've got a file, use this. 📄

populate_objects

$xmsg->populate_objects ($global_hash_ref [, $matching_object
    [, $tag_name [, $tag_content, [$parameter_index]]]])

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 TEMPLATE. so it's like filling in the blanks. 🧩

rexec

$xmsg->rexec ($dbh, $global_hash_ref)

this method is running the created query against a DBI/DBD source and fills in the template with results in order to make them available for subsequent output_message call. in case of INSERT/UPDATE operations only key values will be filled in. so it's executing and populating. 🚀

output_message

this method returns a string with query results in XML format suitable for printing or whatever manipulations seem appropriate. so it's like the grand finale of your query. 🎬

---

👀 SEE ALSO 👀

• XML::Parser
• XML::Parser::Expat

💖 AUTHORS 💖

Andrei Nossov <andrein@andrein.com>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's a wrap, bestie! this page was brought to you by perl v5.34.0, dated 2022-06-13, and it's the XMLMessage(3pm) man page. stay slaying! 💅✨