User and Reference Manual
Altova MapForce 2011 User & Reference
Manual
All rights reserved. No parts of this work may be reproduced in any form or by any means
- graphic, electronic, or mechanical, including photocopying, recording, taping, or
information storage and retrieval systems - without the written permission of the publisher.
Products that are referred to in this document may be either trademarks and/or registered
trademarks of the respective owners. The publisher and the author make no claim to
these trademarks.
While every precaution has been taken in the preparation of this document, the publisher
and the author assume no responsibility for errors or omissions, or for damages resulting
from the use of information contained in this document or from the use of programs and
source code that may accompany it. In no event shall the publisher and the author be
liable for any loss of profit or any other commercial damage caused or alleged to have
been caused directly or indirectly by this document.
Published: 2011
© 2011 Altova GmbH
Table of Contents
1
MapForce 2011
3
2
What's new...
6
3
MapForce overview
3.1
Terminology ................................................................................................................. 12
4
MapForce tutorial
4.1
18
Setting up the .................................................................................................................
mapping environment
4.2
.................................................................................................................
21
Mapping schema
items
4.3
Using functions
.................................................................................................................
to map data
24
4.4
Filtering data ................................................................................................................. 28
4.5
.................................................................................................................
32
Generating XSLT
1.0 and 2.0 code
4.6
33
Multiple target.................................................................................................................
schemas / documents
4.6.1
Viewing and generating
...................................................................................................
multiple target schema output
36
4.7
.................................................................................................................
38
Mapping multiple
source items, to single target items
4.7.1
Creating the mappings
................................................................................................... 39
4.7.2
Duplicating input
...................................................................................................
items
42
4.8
.................................................................................................................
47
Multi-file input
/ output
4.8.1
Processing multiple
...................................................................................................
files per input/output component
48
5
MapForce user interface
5.1
.................................................................................................................
55
Mapping between
components
5.1.1
Missing items................................................................................................... 57
5.2
.................................................................................................................
61
Validating mappings
and mapping output
5.3
Output tab
5.4
Functions and.................................................................................................................
libraries
65
5.4.1
Function context
...................................................................................................
menu
68
Altova MapForce 2011
10
16
54
................................................................................................................. 63
1
6
Methods of mapping data (Standard / Mixed /
Copy All)
70
6.1
72
Source driven.................................................................................................................
/ mixed content mapping
6.2
.................................................................................................................
75
Mapping mixed
content text() nodes
6.3
Mixed content.................................................................................................................
- connection settings
78
6.4
Mixed content.................................................................................................................
example
81
6.5
.................................................................................................................
83
Source-driven/mixed
content Vs. standard mapping
6.6
................................................................................................................. 84
Copy-all connections
6.7
Moving connectors
................................................................................................................. 87
7
Global Resources
7.1
Global Resources
.................................................................................................................
- Files
93
7.1.1
Defining / Adding
global resources
...................................................................................................
94
7.1.2
Assigning a global
...................................................................................................
resource
97
7.1.3
Using / activating
...................................................................................................
a global resource
99
7.2
.................................................................................................................
101
Global Resources
- Folders
7.3
Global Resources
.................................................................................................................
- Application workflow
104
7.3.1
Start application
...................................................................................................
workflow
108
7.4
Global Resources
.................................................................................................................
- Properties
111
8
Dynamic input/output files per component
8.1
Dynamic file.................................................................................................................
names - input / output
118
8.2
121
Dynamic file.................................................................................................................
names as Input parameters
8.3
.................................................................................................................
122
Multiple XML
files from single XML source file
8.4
Relative and .................................................................................................................
absolute file paths
124
9
Loops, groups and hierarchies
130
10
Chained mappings / pass-through
components
138
92
116
10.1 Chained mappings
.................................................................................................................
- Pass-through active
140
.................................................................................................................
144
10.2 Chained mappings
- Pass-through inactive
2
Altova MapForce 2011
11
Intermediate variables
148
.................................................................................................................
153
11.1 Variables - use
cases
12
How To... Filter, Transform, Aggregate
158
.................................................................................................................
160
12.1 Filter - retrieving
dynamic data, lookup table
12.1.1 Filter components
...................................................................................................
- Tips
162
164
12.2 Value-Map -.................................................................................................................
transforming input data
12.2.1 Passing data ...................................................................................................
through a Value-Map unchanged
167
12.2.2 Value-Map component
...................................................................................................
properties
170
.................................................................................................................
171
12.3 Aggregate functions:
min, max, sum, count, avg
.................................................................................................................
173
12.4 Mappings and
root element of target documents
12.5 Boolean comparison
.................................................................................................................
of input nodes
174
12.6 Priority Context
.................................................................................................................
node/item
175
.................................................................................................................
176
12.7 Merging multiple
files into one target
.................................................................................................................
178
12.8 Command line
parameters
12.9 Command line
.................................................................................................................
- defining input/output files
180
12.10 Input parameters
.................................................................................................................
- default and preview settings
182
185
12.11 Node testing,.................................................................................................................
position and grouping
12.11.1 Mapping missing
...................................................................................................
nodes - using Not-exists
187
12.11.2 Position of context
items in a sequence
...................................................................................................
189
12.11.3 Grouping nodes
...................................................................................................
/ node content
191
12.12 Using DTDs.................................................................................................................
as "schema" components
197
12.13 Type conversion
.................................................................................................................
checking
198
199
12.14 Catalog files.................................................................................................................
in MapForce
.................................................................................................................
203
12.15 Derived XML
Schema types - mapping to
12.16 Recursive user-defined
.................................................................................................................
mapping
205
12.16.1 Defining a recursive
...................................................................................................
user-defined function
207
13
StyleVision Power Stylesheets in Preview
214
13.1 Assigning an.................................................................................................................
SPS file to a component
216
14
Documenting mapping projects
220
14.1 Supplied SPS.................................................................................................................
stylesheets
226
229
14.2 User-Defined.................................................................................................................
Design
Altova MapForce 2011
3
15
Nil Values / Nillable
232
16
HL7 v3.x to/from XML schema mapping
236
17
Libraries and Functions
238
.................................................................................................................
239
17.1 Defining User-defined
functions
17.1.1 Function parameters
................................................................................................... 245
17.1.2 Inline and regular
user-defined functions
...................................................................................................
248
17.1.3 Creating a simple
...................................................................................................
look-up function
250
17.1.4 Complex user-defined
...................................................................................................
function - XML node as input
255
...........................................................................................................
256
Complex input components - defining
17.1.5 Complex user-defined
function - XML node as output
...................................................................................................
261
...........................................................................................................
261
Complex
output components - defining
17.1.6 User-defined...................................................................................................
function - example
266
.................................................................................................................
271
17.2 Adding custom
XSLT and XQuery functions
17.2.1 Adding custom
...................................................................................................
XSLT 1.0 functions
272
17.2.2 Adding custom
...................................................................................................
XSLT 2.0 functions
276
17.2.3 Aggregate functions
- summing nodes in XSLT1 and 2
...................................................................................................
277
17.3 Functions Reference
................................................................................................................. 280
17.3.1 core
................................................................................................... 281
........................................................................................................... 281
aggregates
...........................................................................................................
283
conversion
functions
291
file path...........................................................................................................
functions
...........................................................................................................
293
generator
functions
295
logical ...........................................................................................................
functions
........................................................................................................... 297
math functions
........................................................................................................... 299
node functions
...........................................................................................................
302
sequence
functions
........................................................................................................... 303
string functions
..........................................................................................................................
307
Tokenize
examples
..........................................................................................................................
310
Regular expressions
17.3.2
4
xpath2
................................................................................................... 314
........................................................................................................... 314
accessors
314
anyURI...........................................................................................................
functions
315
boolean...........................................................................................................
functions
........................................................................................................... 315
constructors
316
context ...........................................................................................................
functions
Altova MapForce 2011
17.3.3
...........................................................................................................
317
durations,
date and time functions
........................................................................................................... 319
node functions
320
numeric...........................................................................................................
functions
...........................................................................................................
320
qname-related
functions
........................................................................................................... 321
string functions
xslt
................................................................................................... 324
........................................................................................................... 324
xpath functions
........................................................................................................... 326
xslt functions
18
QName support
330
19
User Reference
334
19.1 File
................................................................................................................. 335
19.2 Edit
................................................................................................................. 338
19.3 Insert
................................................................................................................. 339
19.4 Component ................................................................................................................. 341
19.5 Connection ................................................................................................................. 345
19.6 Function
................................................................................................................. 350
19.7 Output
................................................................................................................. 353
19.8 View
................................................................................................................. 355
19.9 Tools
................................................................................................................. 357
19.10 Window
................................................................................................................. 362
19.11 Help Menu ................................................................................................................. 363
19.11.1 Table of Contents,
...................................................................................................
Index, Search
364
19.11.2 Activation, Order
...................................................................................................
Form, Registration, Updates
365
19.11.3 Other Commands
................................................................................................... 366
20
Appendices
368
................................................................................................................. 369
20.1 Engine information
20.1.1 XSLT 1.0 Engine:
...................................................................................................
Implementation Information
370
20.1.2 XSLT 2.0 Engine:
Implementation Information
...................................................................................................
372
372
General...........................................................................................................
Information
...........................................................................................................
374
XSLT 2.0
Elements and Functions
20.1.3 Extensions ................................................................................................... 375
...........................................................................................................
375
Java Extension
Functions
..........................................................................................................................
376
User-Defined
Class Files
..........................................................................................................................
378
User-Defined Jar Files
..........................................................................................................................
379
Java: Constructors
Altova MapForce 2011
5
..........................................................................................................................
Java:
Static Methods and Static Fields
..........................................................................................................................
Java:
Instance Methods and Instance Fields
..........................................................................................................................
Datatypes:
XPath/XQuery to Java
..........................................................................................................................
Datatypes:
Java to XPath/XQuery
380
380
381
382
...........................................................................................................
382
.NET Extension
Functions
..........................................................................................................................
.NET:
Constructors
..........................................................................................................................
.NET:
Static Methods and Static Fields
..........................................................................................................................
.NET:
Instance Methods and Instance Fields
..........................................................................................................................
Datatypes:
XPath/XQuery to .NET
..........................................................................................................................
Datatypes:
.NET to XPath/XQuery
384
385
385
386
387
387
MSXSL...........................................................................................................
Scripts for XSLT
...........................................................................................................
389
Altova Extension Functions
..........................................................................................................................
390
General
Functions
................................................................................................................. 394
20.2 Technical Data
20.2.1 OS and Memory
...................................................................................................
Requirements
395
20.2.2 Altova XML...................................................................................................
Parser
396
20.2.3 Altova XSLT...................................................................................................
and XQuery Engines
397
20.2.4 Unicode Support
................................................................................................... 398
...........................................................................................................
398
Windows XP
...........................................................................................................
399
Right-to-Left
Writing Systems
20.2.5 Internet Usage
................................................................................................... 400
20.3 License Information
................................................................................................................. 401
20.3.1 Electronic Software
Distribution
...................................................................................................
402
20.3.2 Software Activation
...................................................................................................
and License Metering
403
20.3.3 Intellectual Property
...................................................................................................
Rights
404
20.3.4 Altova End User
...................................................................................................
License Agreement
405
Index
6
Altova MapForce 2011
Chapter 1
MapForce 2011
MapForce 2011
1
3
MapForce 2011
MapForce® 2011 Basic Edition is a visual data mapping tool for advanced data integration
projects. MapForce® is a 32/64-bit Windows application that runs on Windows 7, Windows
Vista, Windows Server 2003/2008, and Windows XP. 64-bit support is available for the
Enterprise and Professional editions.
MapForce® supports:
·
Graphical mapping from and to any combination and any number of:
- XML Schemas as source and target
Professional Edition, additionally:
- Flat files: delimited (CSV) and fixed-length formats as source and target
- Relational databases as source and target
Enterprise Edition, additionally:
- EDI files: UN/EDIFACT, ANSI X12 including HIPAA, HL7 2.x, IATA PADIS, and SAP
IDocs as source and target
- FlexText™ files as source and target
- Office Open XML Excel 2007 and higher files, as source and target
- XBRL instance files and taxonomies
·
Automatic code generation
- XSLT 1.0 and 2.0
Professional Edition and Enterprise Edition, additionally:
- XQuery
- Java, C# and C++
- 64-bit version support
·
·
·
·
·
·
·
·
·
·
·
On-the-fly transformation and preview of all mappings, without code generation or
compilation
Ability to preview intermediate components in a mapping chain of two or more
components connected to a target component (pass-through preview).
Ability to preview output of target components using StyleVision Power Stylesheets
Powerful visual function builder for creating user-defined functions
Accessing MapForce user interface and functions through MapForce API (ActiveX
control)
Definition of custom XSLT 1.0 and 2.0 libraries
Support for XPath 2.0 functions in XSLT 2.0 and XQuery
Definition of user-defined functions/components, having complex in/outputs
Support for source-driven / mixed content mapping and copy-all connections
Automatic retention of mapping connectors of missing nodes/items
Support for HL7 version 3.x. as it is XML Schema based
Professional Edition, additionally:
· XML data mapping to/from databases - IBM DB2 and others
· Direct querying of databases
· SQL-WHERE filter and SQL statement wizard
· SQL SELECT statements as mapping data sources
· Integration of custom C++, Java and C# functions
· Project management functions to group mappings
· MapForce plug-in for Eclipse 3.4 / 3.5 / 3.6
· MapForce for Microsoft Visual Studio
· Documentation of the mapping design
© 2011 Altova GmbH
Altova MapForce 2011
4
MapForce 2011
Enterprise Edition, additionally:
· Creation of SOAP 1.1 and SOAP 1.2 Web service projects and mapping of Web
service operations from WSDL 1.1 and 2.0 files
· Direct calling of Web service functions
· FlexText™: advanced legacy file processing
All transformations are available in one workspace where multiple sources and multiple targets
can be mixed, and a rich and extensible function library provides support for any kind of data
manipulation.
What is mapping?
Basically the contents of a component are mapped, or transformed, to another component. An
XML, or text document can be mapped to a different target XML document. The transformation
is accomplished by an automatically generated XSLT 1.0 or 2.0 Stylesheet.
MapForce also has the ability to have a single component process multiple input files of a
directory and output multiple files to a single component as well.
When creating an XSLT transformation, a source schema is mapped to a target schema.
Thus elements/attributes in the source schema are "connected" to other elements/attributes in
the target schema. As an XML document instance is associated to, and defined by, a schema
file, you actually end up mapping two XML documents to each other.
Last updated: 06/07/2011
Altova MapForce 2011
© 2011 Altova GmbH
Chapter 2
What's new...
6
What's new...
2
What's new...
New features in MapForce Version 2011R3 include:
· Intermediate variables
New features in MapForce Version 2011R2 include:
·
·
·
·
·
Find function capability in Library window
Reverse mapping
Extendable IF-ELSE function
Node Name and parsing functions in Core Library
New option of using StyleVision Power Stylesheets when documenting a mapping
New features in MapForce Version 2011 include:
·
·
·
·
·
Ability to preview target components using StyleVision Power Stylesheets
Ability to preview intermediate components in a mapping chain of two or more
components connected to a target component (pass-through preview).
Formatting functions for dateTime and numbers for all supported languages
Enhancement to auto-number function
New timezone functions: remove-timezone and convert-to-utc
New features in MapForce Version 2010 Release 3 include:
·
·
Support for Nillable values, and xsi:nil attribute in XML instance files
Ability to disable automatic casting to target types in XML documents
New features in MapForce Version 2010 Release 2 include:
·
·
Automatic connection of identical child connectors when moving a parent connector
Ability to tokenize input strings for further processing
New features in MapForce Version 2010 include:
·
·
·
·
·
·
Multiple input/output files per component
Upgraded relative path support
xsi:type support allowing use of derived types
New internal data type system
Improved user-defined function navigation
Enhanced handling of mixed content in XML elements
New features in MapForce Version 2009 SP1 include:
·
·
·
Parameter order in user-defined functions can be user-defined
Ability to process XML files that are not valid against XML Schema
Regular (Standard) user-defined functions now support complex hierarchical
parameters
Altova MapForce 2011
© 2011 Altova GmbH
What's new...
7
New features in MapForce Version 2009 include:
·
·
·
·
·
EDI HL7 versions 3.x XML as source and target components
Grouping of nodes or node content
Ability to filter data based on a nodes position in a sequence
QName support
Item/node search in components
New features in MapForce Version 2008 Release 2 include:
·
·
·
Ability to automatically generate XML Schemas for XML files
Support for Altova Global Resources
Performance optimizations
New features in MapForce Version 2008 include:
·
·
·
·
Aggregate functions
Value-Map lookup component
Enhanced XML output options: pretty print XML output, omit XML schema reference
and Encoding settings for individual components
Various internal updates
New features in MapForce Version 2007 Release 3 include:
·
© 2011 Altova GmbH
Altova MapForce 2011
Chapter 3
MapForce overview
10
MapForce overview
3
MapForce overview
Altova web site:
Introduction to MapForce
MapForce has four main areas: the Library pane at left, the Mapping tab group at right, as well
as the Overview and Messages panes below. The actual mapping process is achieved by
manipulating the on-screen graphical elements in the mapping window.
·
The Libraries pane displays language specific and user defined libraries, as well as the
individual library functions. Functions can be directly dragged into the Mapping tab. The
Add/Remove Libraries... button allows you to import external libraries.
·
The Mapping tab displays the graphical elements used to create the mapping
(transformation) between the two components. E.g. the source schema is the "
mf-ExpReport" component window displaying the source schema tree. The target
schema is the "ExpReport-Target" window displaying the target schema tree.
Connectors connect the input and output icons of each schema item. Schema items
can be either elements or attributes.
The XSLT, XSLT2 tabs display a preview of the transformation depending on the
specific language selected.
The Output tab displays a preview of the transformed, or mapped data, in a text view.
·
The Overview pane displays the mapping area as a red rectangle, which you can drag
to navigate your Mapping.
·
The Messages pane displays any validation warnings or error messages that might
occur during the mapping process. Clicking a message in this pane, highlights it in the
Mapping tab for you to correct.
Altova MapForce 2011
© 2011 Altova GmbH
MapForce overview
11
XSLT selected
© 2011 Altova GmbH
Altova MapForce 2011
12
MapForce overview
3.1
Terminology
Terminology
Library
A Library is a collection of functions visible in the Libraries window. There are several types of
functions, core and language specific, as well as user-defined and custom functions. Please
see the section on functions for more details.
Component
In MapForce many of graphical elements you can insert/import or place in the Mapping tab,
become components. Components have small triangles which allow you to map data between
source and target components by creating connections between them.
The following files become components when placed in the mapping area:
·
·
·
Schemas and DTDs: Source and target schemas
Function types: XSLT/XSLT2, as well as Constants, Filters and Conditions
Function
A function is predefined component that operates on data e.g. Concat. Functions have input
and/or output parameters, where each parameter has its own input/output icon. Functions are
available in the Libraries window and are logically grouped; hitting CTRL+F allows you to search
for a function. Dragging a function into the Mapping window creates a function component.
Please see the section Functions and Libraries for more details.
Java selected
Item
An item represents the data that can be mapped from component to component. An item can
be either an element, an attribute.
Each item has an input and output icon. It is not mandatory that items be of the same type
(element or attribute) when you create a mapping between them.
Input, Output icon
Altova MapForce 2011
© 2011 Altova GmbH
MapForce overview
Terminology
13
The small triangles visible on components are input and output icons. Clicking an icon and
dragging, creates a connector which connects to another icon when you "drop" it there. The
connector represents a mapping between the two sets of data the icons represent. Please see
the section "Mapping between components" for more information.
Connector
The connector is the line that joins two icons. It represents the mapping between the two sets
of data the icons represent. Please see the section "Mapping between components" for more
information.
Several types of connector can be defined:
· Target Driven (Standard) connectors, see: "source-driven / mixed content vs. standard
mapping"
· Copy-all connectors, please see "Copy-all connections"
· Source Driven (mixed content) connectors, see "source driven and mixed content
mapping"
Constant
A constant is a component that supplies fixed data to an input icon of a function or component.
E.g. the string "Travel" is connected to the "b" parameter of the equal function . The data is
entered into a dialog box when creating, or double clicking, the component. There is only one
output icon on a constant function. You can select from the following types of data: String,
Number, and All other (String).
Variable
Inserts an Intermediate Variable which is equivalent to a regular (non-inline) user-defined
function. Variables are structural components, without instance files, and are used to simplify
the mapping process.
Filter: Node/Row
A filter is a component that filters data using two input and output parameters: node/row and
bool, and on-true, on-false. If the Boolean is true, then the value/content of the node/row
parameter is forwarded to the on-true parameter.
© 2011 Altova GmbH
Altova MapForce 2011
14
MapForce overview
Terminology
The on-false output parameter, outputs the complement node set defined by the mapping,
please see Multiple target schemas / documents for more information.
Value-Map
The Value-Map component allows you to transform a set of input data, into a different set of
output data, using a type of lookup table.
Double clicking the component, opens the value map table. The left column of the table defines
the input, while the right column defines the transformed data you want to output.
IF-Else Condition
A condition is a component which allows you to pass on different sets of data depending on the
outcome of a preset condition. The component header displays the text if-else. Please see
Condition, in the Reference section for an example.
·
·
·
·
The first input parameter is a bool, which contains the data you are checking against.
The value-true input parameter supplies the data to be passed on, as a result, if the
condition is true.
The value-false supplies the data to be passed on if the condition is false.
The result parameter outputs the data supplied by the value-true/false input
parameters.
The IF-Else function is now extendable. This means that you can check for multiple IF values
and use the otherwise parameter to output the Else condition/value. Please see Insert | If-Else
for more information.
Altova MapForce 2011
© 2011 Altova GmbH
Chapter 4
MapForce tutorial
16
MapForce tutorial
4
MapForce tutorial
Tutorial example:
In this tutorial, a simple employee travel expense report will be mapped to a more complex
company report.
Each employee fills in the fields of the personal report. This report is mapped to the company
report and routed to the Administration department. Extra data now has to be entered in
conjunction with the employee, the result being a standardized company expense report.
Aim of the tutorial:
· To transform the personal expense report to a company expense travel report
· Selectively filter the source data and only let the travel expense records through
· Generate an XSLT transformation file
· Transform the personal expense report to the company expense report using the
generated XSLT file
The tutorial makes use of the following components:
· source and (multiple) target schemas
· several functions including: concat, filter, equal and constants
Files used in the tutorial:
All the files used in this tutorial are initally available in the C:\Documents and Settings\All
Users\Application Data\Altova folder. When any single user starts the application for the first
time, the example files for that user are copied to ...\MapForceExamples\Tutorial\ folder.
Therefore do not move, edit, or delete the example files in the initial ...\All Users\.... directory.
The XSLT and transformed XML files are also supplied.
Tutorial files:
Personal expense report
Tut-ExpReport.mfd
The expense report mapping (single target)
Tut-ExpReport-multi.mf The multi-schema target expense report mapping
d
mf-ExpReport.xml
mf-ExpReport.xsd
Personal expense report XML instance document
Associated schema file
Company expense report
ExpReport-Target.xml Company expense report XML instance document
ExpReport-Target.xsd Associated schema file
File paths in Windows XP, Windows Vista, and Windows 7
File paths given in this documentation will not be the same for all operating systems. You
should note the following correspondences:
·
(My) Documents folder: The My Documents folder of Windows XP is the Documents
folder of Windows Vista and Windows 7. It is located by default at the following
respective locations. Example files are usually located in a sub-folder of the (My)
Documents folder.
C:\Documents and Settings\<username>\My
Documents
Windows Vista, Windows 7 C:\Users\<username>\Documents
Windows XP
Altova MapForce 2011
© 2011 Altova GmbH
MapForce tutorial
·
17
Application folder: The Application folder is the folder where your Altova application is
located. The path to the Application folder is, by default, the following.
C:\Program Files\Altova
Windows XP
Windows Vista, Windows 7 C:\Program Files\Altova
32 bit Version on 64-bit OS C:\Program Files (x86)\Altova
© 2011 Altova GmbH
Altova MapForce 2011
18
MapForce tutorial
4.1
Setting up the mapping environment
Setting up the mapping environment
This section deals with defining the source and target schemas we want to use for the mapping.
·
Start MapForce.
Creating the source schema component:
1. Click the Insert XML Schema/File
icon.
2. Select the mf-ExpReport.xsd file from the Open dialog box.
You are now prompted for a sample XML file to provide the data for the preview tab.
3. Click the Browse... button, and select the mf-ExpReport.xml file.
The source schema component now appears in the Mapping tab.
XSLT selected
4. Click the expense-report item/element (of the component) and hit the * key, on the
numeric keypad, to view all the items.
5. Click the resize corner
at the lower right of the component window, and drag to
resize the window.
Note: double clicking the resize corner, resizes the component to a "best fit",
encompassing all items.
Altova MapForce 2011
© 2011 Altova GmbH
MapForce tutorial
Setting up the mapping environment
19
XSLT Selected
Please note:
MapForce can automatically generate an XML schema based on an existing XML file,
if the XML Schema is not available. A dialog box automatically appears, prompting you
if an accompanying XML Schema file cannot be found when inserting an XML file using
the Insert XML Schema / File menu item.
When generating a schema from an XML file, datatypes for elements/attributes must be
inferred from the XML instance document and may not be exactly what you expect.
Please check whether the generated schema is an accurate representation of the
instance data.
Creating the target schema component:
1. Click the Insert XML Schema/File icon.
2. Select the ExpReport-Target.xsd file from the Open dialog box.
You are now prompted for a sample XML file for this schema.
3. Click the Skip button, and select Company as the root element of the target document.
© 2011 Altova GmbH
Altova MapForce 2011
20
MapForce tutorial
Setting up the mapping environment
The target schema component now appears in the mapping tab.
4. Click the Company entry and hit the * key on the numeric keypad to view all the items.
5. Click the expand window icon and resize the window.
We are now ready to start mapping schema items from the source to the target
schema.
Altova MapForce 2011
© 2011 Altova GmbH
MapForce tutorial
4.2
Mapping schema items
21
Mapping schema items
Altova web site:
Mapping data - data integration and XML mapping
This section deals with defining the mappings between the source and target schema items.
1. Click the expense-report item in the source schema and drag.
A connector line is automatically created from the output icon and is linked to the
mouse pointer which has now changed shape.
2. Move the mouse pointer near to the Company item in the target schema, and "drop"
the connector the moment the mouse pointer changes back to the arrow shape. A
small link icon appears below the mouse pointer, and the input icon and item name in
the target component, are highlighted when the drop action is possible.
A connector has now been placed between the source and target schemas. A mapping
has now been created from the schema source to the target document.
3. Use the above method to create a mapping between the Person and Employee items.
If the Autoconnect children icon is active
, then the Title and Email items will also
be connected, if not:
4. Right click the "Person" connector and select "Connect Matching Children" from the
pop-up menu.
© 2011 Altova GmbH
Altova MapForce 2011
22
MapForce tutorial
Mapping schema items
This opens the Connect Matching Children dialog box.
5. Activate the check boxes as shown above and click OK to confirm. For more
information please see the section on Connector properties.
Mappings have been automatically created for the Title and Email items of both
schemas.
6. Click the Output tab to see if there is a result.
Altova MapForce 2011
© 2011 Altova GmbH
MapForce tutorial
Mapping schema items
23
You will notice that the Title and Email fields contain data originating from the XML
Instance document.
7. Click the Mapping tab to continue mapping.
Please note:
The settings you select in the Connect Matching Children dialog box, are retained until
you change them. These settings can be applied to a connection by either: using the
context menu, or by clicking the Auto connect child items icon to activate, or deactivate
this option.
© 2011 Altova GmbH
Altova MapForce 2011
24
MapForce tutorial
4.3
Using functions to map data
Using functions to map data
The aim of this section is to combine two sets of data from the source schema, and place the
result in a single item in the target document. Please note, that some of the previously defined
mappings are not shown in the following screen shots for the sake of clarity.
This will be done by:
· Using the Concat string function to combine the First and Last elements of the source
schema
· Using a Constant function to supply the space character needed to separate both
items
· Placing the result of this process into the Name item of the target schema.
Using functions to combine items:
1. Click the concat entry of the string functions group, in the Core library, and drag it into
the Mapping tab.
XSLT Selected
2. Create a connection between item First and value1 of the concat component.
3. Right click on the background near value2 and select Insert Constant from the context
menu, to insert a constant component.
Altova MapForce 2011
© 2011 Altova GmbH
MapForce tutorial
Using functions to map data
25
4. Enter a space character in the text box and click OK.
The constant component is now in the working area. Its contents are displayed next to
the output icon.
5. Create a connection between the constant component and value2 of the concat
component.
6. Click the item Last and drop the connector on the "+" icon of the concat function, just
below value2. The mouse cursor changes to show when you can drop the connector.
This automatically enlarges the concat function by one more item (value), to which the
Last item is connected.
© 2011 Altova GmbH
Altova MapForce 2011
26
MapForce tutorial
Using functions to map data
7. Connect the result icon of the concat component, to the Name item in the target
schema.
8. Click the Output tab to see the result of the current mapping.
You will see that the Person name "Fred Landis" is now contained between the Name
tags. The first and last name have been separated by a space character as well.
Mapping the rest of the personal data:
1. Create mappings between the following items:
· currency to Currency
· Phone to Tel.
· expto to Bill-to
· Date to Date
Altova MapForce 2011
© 2011 Altova GmbH
MapForce tutorial
Using functions to map data
27
2. Click the Output tab to see the result.
There are currently five items originating from the assigned XML instance file.
Please note:
Functions can be grouped into user-defined functions/components to optimize screen usage.
Please see the section on "User-defined functions/components" for an example on how to
combine the concat and constant functions into a single user-defined function/component.
© 2011 Altova GmbH
Altova MapForce 2011
28
MapForce tutorial
4.4
Filtering data
Filtering data
The aim of this section is to filter out the Lodging and Meal expenses, and only pass on the
Travel expenses to the target schema/document.
This will be done by:
· Using the Equal function to test the value of a source item
· Using a Constant function to supply the comparison string that is to be tested
· Using the Filter function which passes on the Travel data, if the bool input value is true
· Placing the on-true result of this process, into the expense-item element of the target
schema/document.
Filtering data:
1. Insert a constant component and enter the string Travel into the input field.
2. Insert the logical function equal from the core library (logical functions group).
3. Connect the (expense-item) type item in the source schema, to the a parameter of the
equal function.
4. Connect the result icon of the constant component, to the b parameter of the equal
function.
Altova MapForce 2011
© 2011 Altova GmbH
MapForce tutorial
Filtering data
29
5. Select the menu option Insert | Filter: Nodes/Rows.
6. Connect the result icon of the equal component, to the bool parameter of the filter
component.
7. Connect the expense-item icon of the source schema with the node/row parameter of
the filter component.
Note that the filter component name, now changes to "expense-item".
© 2011 Altova GmbH
Altova MapForce 2011
30
MapForce tutorial
Filtering data
8. Connect the on-true icon of the filter component with the expense-item element of the
target document.
9. Connect the Travel item in the source schema, with the Travel item in the target
schema/document.
10. Connect the Trav-cost item with the Travel-Cost item in the target schema/document.
11. Click the Output tab to see the result.
Altova MapForce 2011
© 2011 Altova GmbH
MapForce tutorial
Filtering data
31
Please note:
The on-false parameter of the filter component, outputs the complement node set that
is mapped by the on-true parameter. In this example it would mean all non-travel
expense items.
The number of expense-items have been reduced to three. Checking against the supplied
mf-ExpReport.xml file, reveals that only the Travel records remain, the Lodging and Meal
records have been filtered out.
© 2011 Altova GmbH
Altova MapForce 2011
32
MapForce tutorial
4.5
Generating XSLT 1.0 and 2.0 code
Generating XSLT 1.0 and 2.0 code
MapForce can generate two flavors of XSLT code:
1. Select the menu item File | Generate code in | XSLT 1.0 (or XSLT 2.0).
2. Select the folder you want to place the generated XSLT file in, and click OK.
A message appears showing that the generation was successful.
3. Navigate to the designated folder and you will find the XSLT with the file name
MappingMapToExpReport-Target.xslt (i.e. in the form:
MappingMapToTargetSchemaName)
The folder also contains a batch file called DoTransform.bat which uses AltovaXML to
transform the XML file.
To transform the personal expense report to the company expense report:
1. Download and install the free AltovaXML engine from the AltovaXML download page.
AltovaXML is installed to c:\Program Files\Altova\AltovaXML2011\ per default.
2. Start the DoTransform.bat batch file located in the previously designated output
folder.
This generates the output file ExpReport-Target.xml in the current folder.
Note:
you might need to add the AltovaXML installation location to the path variable of the
Environment Variables.
Altova MapForce 2011
© 2011 Altova GmbH
MapForce tutorial
4.6
Multiple target schemas / documents
33
Multiple target schemas / documents
This section deals with creating a second target schema / document, into which non-travel
expense records will be placed, and follows on from the current tutorial example
Tut-ExpReport.mfd.
Creating the second target schema component:
1. Click the Insert XML Schema/File icon.
2. Select the ExpReport-Target.xsd file from the Open dialog box.
You are now prompted for a sample XML file for this schema.
3. Click Skip, and select Company as the root element of the target document.
The target schema component now appears in the Mapping tab.
4. Click the Company entry and hit the * key on the numeric keypad to view all the items.
5. Click the expand window icon and resize the component. Place the schema
components so that you can view and work on them easily.
There is now one source schema, mf-expReport, and two target schemas, both
ExpReport-Target, visible in the Mapping tab.
Filtering out the non-travel data:
1. Connect the on-false icon of the filter component with the expense-item element of
the second target schema / document.
A message appears stating that you are now working with multiple target schemas /
documents.
© 2011 Altova GmbH
Altova MapForce 2011
34
MapForce tutorial
Multiple target schemas / documents
2. Click OK to confirm.
A Preview icon is now visible in the title bar of each target schema component.
Clicking the Preview icon defines which of the target schema data is to be displayed,
when you subsequently click the XSLT, XSLT2, XQuery, or Output tabs.
Creating mappings for the rest of the expense report data:
1. Connect the Lodging item in the source schema to Accommodation in the second
target schema.
2. Connect the Lodging item to DomesticAcc.
3. Connect the Lodge-Cost item to DomesicAcc-Cost.
4. Create the following mappings between the source schema and second target schema.
You created the same connectors for the first target schema, so there is nothing new
here:
Source schema - connect:
to... second Target schema
Person
Result of existing First
and Last concatenation
Title
Phone
Email
currency
expto
Date
Employee
Altova MapForce 2011
Name
Title
Tel.
Email
Currency
Bill-to
Date
© 2011 Altova GmbH
MapForce tutorial
© 2011 Altova GmbH
Multiple target schemas / documents
35
Altova MapForce 2011
36
MapForce tutorial
Multiple target schemas / documents
4.6.1
Viewing and generating multiple target schema output
Clicking the Preview icon lets you select which of the schema targets you want to preview.
To view specific XSLT output:
1. Click the Preview icon
in the title bar of the second schema component, to make
it active (if not already active).
2. Click the Output tab of the Mapping tab group.
The XML output contains two records both billed to Sales: the Domestic
Accommodation cost of $121.2 and an Expense-item record which only contains a
date. This record originates from the expense-item Meal. There is currently no mapping
between meal costs and domestic accommodation costs, and even if there were, no
cost would appear as the XML instance does not supply one.
Please note:
You can save this XML data by clicking the Save generated output icon, while viewing
the XML output in the preview window
.
The resulting XML instance file can also be validated against the target schema, by
clicking the validate button
.
To generate XSLT 1.0 / XSLT 2.0 code for multiple target schemas:
1. Select the menu item File | Generate code in | XSLT 1.0 (or XSLT 2.0).
2. Select the folder you want to place the generated XSLT files, and click OK.
A message appears showing that the generation was successful.
Altova MapForce 2011
© 2011 Altova GmbH
MapForce tutorial
Multiple target schemas / documents
37
3. Navigate to the designated folder and you will find two XSLT files with the file names:
MappingExpReport-Target.xslt and MappingExpReport-Target2.xslt
To transform the personal expense report to the company expense report:
1. Download and install the free AltovaXML engine from the AltovaXML download page.
AltovaXML is installed to c:\Program Files\Altova\AltovaXML2011\ per default.
2. Start the DoTransform.bat batch file located in the previously designated output
folder.
This generates the output file ExpReport-Target.xml in the current folder.
Note: you might need to add the AltovaXML insallation location to the path variable of
the Environment Variables.
© 2011 Altova GmbH
Altova MapForce 2011
38
MapForce tutorial
Mapping multiple source items, to single target items
4.7
Mapping multiple source items, to single target items
In this section two simple employee travel expense reports will be mapped to a single company
report. This example is a simplified version of the mapping you have already worked through in
the Multiple target schemas / documents section of this tutorial.
Please note:
There is an alternative method to doing this using the dynamic input/output functionality
of components, please see "Dynamic file names - input / output" for a specific
example.
Aim of this section:
To merge two personal travel expense reports into a company expense travel report.
Please note that the files used in this example, have been optimized to show how to map data
from two input XML files into a single item in the target schema, this is not meant to be a
real-life example.
Files used in this section:
mf-ExpReport.xml
mf-ExpReport2.xml
mf-ExpReport-combined.xml
Input XML file used in previous section
The second input XML file
The resulting file when the mapping has
been successful
ExpReport-combined.xsd
The target schema file into which the two
XML source data will be merged.
Tut-ExpReport-msource.mfd
The mapping file for this example
Please note:
The files used in this section are also available in the ...\MapForceExamples\Tutorial\
folder.
Altova MapForce 2011
© 2011 Altova GmbH
MapForce tutorial
4.7.1
Mapping multiple source items, to single target items
39
Creating the mappings
The method described below, is a recapitulation of how to set up the mapping environment.
This mapping is available as Tut-ExpReport-msource.mfd in the
...\MapForceExamples\Tutorial\.
1. Click the Insert XML Schema/File icon.
2. Select the mf-ExpReport.xsd file from the Open dialog box, click Browse... and select
the mf-ExpReport.xml file as the XML instance file.
3. Click the expense-report entry, hit the * key on the numeric keypad to view all the
items; resize the component if necessary.
4. Click the Insert XML Schema/File icon.
5. Select the ExpReport-combined.xsd file from the Open dialog box.
You are now prompted for a sample XML file for this schema.
6. Click Skip, and select Company as the root element of the target document.
7.
The target schema component now appears in the mapping tab.
Click the Company entry, hit the * key on the numeric keypad to view all the items, and
resize the window if necessary.
Make sure that the "Auto connect child items" icon
create the following mappings.
is deactivated, before you
Create the following mappings between the two components:
· Expense-report to Company
· Person to Employee
· Last to Name
· Title to Title
· Phone to Tel.
· Email to Email
· expense-item to expense-item
© 2011 Altova GmbH
Altova MapForce 2011
40
MapForce tutorial
·
·
Mapping multiple source items, to single target items
Travel to Travel and
Trav-cost to Travel-Cost.
The mapping is shown below.
8. Click the Output tab to see the result of the current mapping.
Please note:
Empty <expense-item/> elements/tags are generated when child items of a mapped
parent item, exist in the source file, which have not been mapped to the target
schema. In this case, only the travel items of the expense-item parent have been
Altova MapForce 2011
© 2011 Altova GmbH
MapForce tutorial
Mapping multiple source items, to single target items
41
mapped. There are however, two other expense items in the list: one lodging and one
meal expense item. Each one of these items generates an empty parent expense-item
tag.
To avoid generating empty tags, create a filter such as the one described previously in
the tutorial, under Filtering data, or connect the Travel item to the expense-item.
© 2011 Altova GmbH
Altova MapForce 2011
42
MapForce tutorial
4.7.2
Duplicating input items
Mapping multiple source items, to single target items
We now need to duplicate the input items of the target component to be able to create
mappings from a different source XML file. To achieve this we will:
·
·
add the second XML source file, and
create mappings from it, to the "same" inputs of the duplicated element/item in the
target XML file.
Duplicating input items:
1. Right click the Employee item in the target XML file.
2. Select the menu option Add Duplicate Input After.
A second Employee item has now been added to the component, as Employee(2).
3. Click the expand icon to see the items below it.
The structure of the new Employee item, is an exact copy of the original, except for the
fact that there are no output icons for the duplicated items.
Altova MapForce 2011
© 2011 Altova GmbH
MapForce tutorial
Mapping multiple source items, to single target items
43
You can now use these new duplicate items as the target for the second source XML
data file.
Use the same method as before, to insert the second XML instance file:
1. Click the Insert XML Schema/File icon.
2. Select the mf-ExpReport.xsd file from the Open dialog box, click Browse..., and select
the mf-ExpReport2.xml file as the XML instance file.
3. Click the expense-report entry, hit the * key on the numeric keypad to view all items,
and resize the component if necessary.
For the sake of clarity, the new component has been placed between the two existing
ones in the following graphics.
4. Create the same mappings that were defined for the first XML source file:
·
·
·
·
© 2011 Altova GmbH
Person to Employee(2)
Last to Name
Title to Title
Phone to Tel.
Altova MapForce 2011
44
MapForce tutorial
·
·
·
·
Mapping multiple source items, to single target items
Email to Email
expense-item to expense-item
Scroll down, and map Travel to Travel, and
Trav-cost to Travel-Cost.
5. Click the Output tab to see the result of the mapping.
Altova MapForce 2011
© 2011 Altova GmbH
MapForce tutorial
Mapping multiple source items, to single target items
45
The data of the second expense report has been added to the output file. Johnson and
his travel costs have been added to the expense items of Fred Landis in the company
expense report.
To save the generated output to a file:
·
Click the Save icon
which appears in the title bar when the Output tab is active.
The file, mf-ExpReport-combined.xml, is available in the
...\MapForceExamples\Tutorial\ folder.
To remove duplicated items:
· Right click the duplicate item and select the Remove Duplicate entry from the menu.
To see a further example involving duplicate items, please see the PersonList.mfd
sample file available in the ...\MapForceExamples folder.
In the PersonList.mfd example:
·
Different elements of the source document are mapped to the "same" element in the
© 2011 Altova GmbH
Altova MapForce 2011
46
MapForce tutorial
·
Mapping multiple source items, to single target items
target Schema/XML document.
Specific elements (Manager etc.) are mapped to a generic one using a "role" attribute.
Altova MapForce 2011
© 2011 Altova GmbH
MapForce tutorial
4.8
Multi-file input / output
47
Multi-file input / output
In this section the new multi-file input/output capabilities of MapForce will be demonstrated.
A single input component will process two source documents, while a single output component
will generate two output files. The example used here has been set up in Filtering data, and also
been used as the basis in the Mapping multiple source items, to single target items section.
Aim of this section:
To create a mapping where the source component processes two XML input files and the target
component outputs two XML target files.
Files used in this section:
mf-ExpReport.xml
mf-ExpReport2.xml
Input XML file used in previous section
The second input XML file
Tut-ExpReport-multi.mfd
The mapping file for this example
Please note:
The files used in this section are also available in the ...\MapForceExamples\Tutorial\
folder.
© 2011 Altova GmbH
Altova MapForce 2011
48
MapForce tutorial
4.8.1
Processing multiple files per input/output component
Multi-file input / output
The Tut-ExpReport.mfd file available in the ...\MapForceExamples folder will be modified and
saved under a different name in this example.
Please take note of the following items at the top of each component:
· The File:mf-ExpReport.xml item of mf-ExpReport, displays the Input/Output-XML file
entry. One entry is shown if Input and Output files are the same; if not then Input file
name;Output file name is displayed.
This is automatically filled when you assign an XML instance file to an XML schema
file.
·
The File: (default) item of ExpReport-Target shows that an instance file was not
assigned to the XML schema component when it was inserted, i.e. the Output-XML file
field is empty. A default value will therefore be used when the mapping executes.
Processing multiple files:
Having opened the Tut-ExpReport file available in the ...\Tutorial folder:
1. Double click the mf-ExpReport component on the left.
2. Enter mf-expReport?.xml in the Input XML File field.
Altova MapForce 2011
© 2011 Altova GmbH
MapForce tutorial
Multi-file input / output
49
The wildcard characters ? and * are supported in file names. Note that a relative path
was entered here, as the Tut-ExpReport.mfd file is available in the ...\Tutorial folder
(you can enter an absolute path if you want).
3. Insert the replace-fileext function from the file path functions library, then insert a
constant component.
4. Enter ".out" into the constant component, and connect it to the extension parameter of
the function.
5. Connect the File:mf-ExpReport?.xml item of the component to the filepath parameter
of the function.
6. Connect the result-filepath parameter of the function, to the File <dynamic> item of the
target component.
The File: item of the target component has also changed to File: <dynamic>.
7. Click the Output button to see the results.
The Output window now shows the results for each input XML file in the preview
window, e.g. Preview 1 of 2 as shown below.
© 2011 Altova GmbH
Altova MapForce 2011
50
MapForce tutorial
Multi-file input / output
8. Click the scroll arrow to show the result of the second input XML file.
Note that the combo box shows the name of each of the source XML files; with the *.
xml extension replaced by the *.out extension.
Altova MapForce 2011
© 2011 Altova GmbH
MapForce tutorial
Multi-file input / output
51
Clicking the Save All icon
lets you save all the mapped files from the Preview
window without having to generate code. A prompt appears if output files at the same
location will be overwritten.
9. Save the mapping file under a new name.
Note: please see Dynamic input/output for more information on multiple input / output
files.
© 2011 Altova GmbH
Altova MapForce 2011
Chapter 5
MapForce user interface
54
MapForce user interface
5
MapForce user interface
The following section describes the MapForce user interface and other general tasks not
covered by the tutorial.
Mapping between components
Validating mappings and mapping outputFunctions and libraries
Loops, groups and hierarchies
Altova MapForce 2011
© 2011 Altova GmbH
MapForce user interface
5.1
Mapping between components
55
Mapping between components
A connector visualizes the mapping between the two sets of data and allows the source data
(value) to appear, or be transformed, into the target component e.g. schema/document etc.
·
·
·
·
·
Components and functions have small "connection" triangles called: input or output
icons. These icons are positioned to the left and/or right of all "mappable" items.
Clicking an icon and dragging, creates the mapping connector. You can now drop it
on another icon. A link icon appears next to the text cursor when the drop action is
allowed.
Clicking an item name (element/attribute) automatically selects the correct icon for the
dragging action.
An input icon can only have one connector.
If you try and connect a second connector to it, a prompt appears asking if you want to
replace or duplicate the input icon.
An output icon can have several connectors, each to a different input icon.
·
Positioning the mouse pointer over the straight section of a connector (close to the
input/output icon) highlights it, and causes a popup to appear. The popup displays the
name(s) of the item(s) at the other end of the connector. If multiple connnectors have
been defined from the same output icon, then a maximum of ten item names will be
displayed. The screenshot above shows that the two target items are SinglePrice and
value2 of the multiply function.
·
To move a connector to a different item, point to the straight section of the connector
and drag it elsewhere.
·
To create a duplicate connector from the same source to another target, point to the
straight section of the connector near the original target, and drag it to another target
© 2011 Altova GmbH
Altova MapForce 2011
56
MapForce user interface
Mapping between components
while holding down the CTRL key.
To search for a specific node/item in a component:
1. Click the component you want to search in, and press the CTRL+F keys.
2. Enter the search term and click OK.
The Advanced options visible in the screenshot above, allow you to define which
items/nodes are to be searched, as well as restrict the search options based on the
specific connections.
Autoconnecting items
Activating the autoconnect child items icon
, and creating a connector between two items,
automatically connects all child items of the same name under the parent item.
Number of connectors
Input and output icons appear on most components, there is not, however, a one to one
relationship between their numbers.
·
·
·
·
·
·
Each schema item (element/attribute) has an input and output icon.
Schema components within user-defined functions only have output icons.
Duplicated items only have input icons. This allows you to map multiple inputs to them.
Please see Duplicating Input items for more information.
Functions can have any number of input and output icons, one for each parameter.
E.g. the Add Function has two (or more) input icons, and one output icon.
Special components, can have any number of icons, e.g. the Constant component only
has an output icon.
Altova MapForce 2011
© 2011 Altova GmbH
MapForce user interface
5.1.1
Mapping between components
57
Missing items
Over time, it is likely that the structure of one of the components in a mapping may change e.g.
elements or attributes are added/deleted to an XML schema. MapForce uses placeholder items
to retain all the connectors, and any relevant connection data between components, when items
have been deleted.
Example:
Using the MFCompany.xsd schema file as an example. The schema is renamed to
MyCompany.xsd and a connector is created between the Company item in both schemas. This
creates connectors for all child items between the components, if the Autoconnect Matching
Children is active.
While editing MyCompany.xsd, in XMLSpy, the First and Last items in the schema are deleted.
Returning to MapForce opens a Changed Files notification dialog box, prompting you to reload
the schema. Clicking Reload updates the components in MapForce.
The deleted items and their connectors are now marked in the MyCompany component. You
could now reconnect the connectors to other items if necessary, or delete the connectors.
Note that you can still preview the mapping (or generate code), but warnings will appear in the
Messages window if you do so at this point. All connections to, and from, missing items are
ignored during preview or code-generation.
Clicking one of the highlighted connectors and deleting it, removes the "missing" item from the
© 2011 Altova GmbH
Altova MapForce 2011
58
MapForce user interface
Mapping between components
component, e.g. Last, in MyCompany.
Renamed items:
If a parent item is renamed e.g. Person to ZPerson, then the original parent item connector is
retained and the child items and their connectors are deleted.
"Copy all" connectors and missing items:
Copy all connections are treated in the same way as normal connections, with the only
difference being that the connectors to the missing child items are not retained or displayed.
Renamed or deleted component sources:
If the data source of a component i.e. schema has been renamed or deleted, then all items it
contained are highlighted. The red frame around the component denotes that there is no valid
connection to a schema and prevents preview and code generation.
Altova MapForce 2011
© 2011 Altova GmbH
MapForce user interface
Mapping between components
59
Placing the mouse cursor over the highlighted component, opens a popup containing pertinent
information.
Double clicking the title bar of the highlighted component opens the Component Settings dialog
box. Clicking the Browse button in the Schema file group allows you to select a different, or
backed-up version of the schema. Please see "Component" in the Reference section for more
information.
© 2011 Altova GmbH
Altova MapForce 2011
60
MapForce user interface
Mapping between components
All valid/correct connections will be retained if you select a schema of the same structure.
Altova MapForce 2011
© 2011 Altova GmbH
MapForce user interface
5.2
Validating mappings and mapping output
61
Validating mappings and mapping output
Connectors and validation
It is not mandatory for functions or components to be mapped. The Mapping tab is a work area
where you can place any available components. XSLT 1.0, XSLT 2 is only generated for those
components for which valid connections exist.
To validate a mapping:
·
Click the Validate Mapping icon
File | Validate Mapping.
in the application toolbar, or select the menu item
A validation message appears in the Messages window.
Note that you can use multiple message tabs if your project contains many separate
mapping files. Click one of the numbered tabs in the Messages window, and click the
preview tab for a different mapping in your project. The validation message now
appears in the tab that you selected. The original message in tab 1, is retained
however.
Use the different icons of the Messages tab to:
· Filter the message types, errors or warnings
· Scroll through the entries
· Copy message text to the clipboard
· Find a specific string in a message
· Clear the message window.
Validation messages:
·
Validation successful - X Error(s), Y Warning(s).
Warnings, alert you to something, while still enabling the mapping process and preview
of the transformation result to continue. It is therefore possible for a mapping to have 0
errors and Y warnings.
Errors, halt the transformation process and deliver an error message. An XSLT,
XQuery, or Output preview is not possible when an error of this type exists. Clicking a
validation message in the Messages window, highlights the offending component icon
in the Mapping window.
Component connections and validation results:
Free standing components
· Do not generate any type of error or warning message.
Partially connected components can generate two types of warning:
·
If a function component input icon is unconnected, an error message is generated and
the transformation is halted.
·
If the function output icon is unconnected, then a warning is generated and the
transformation process continues. The offending component and its data are ignored,
© 2011 Altova GmbH
Altova MapForce 2011
62
MapForce user interface
Validating mappings and mapping output
and are not mapped to the target document.
To validate the mapping OUTPUT:
Clicking the Output tab uses the MapForce, XSLT 1.0/2.0 or XQuery engine, to transform the
data and produce a result in a Text view.
If the data is mapped to an XML Schema, then the resulting XML document can be validated
against the underlying schema.
·
Click the Validate button
to validate the document against the schema. A "Output
XML document is valid" message, or a message detailing any errors appears.
Please note:
The entry in the Add Schema/DTD reference field of the component settings dialog box allows
you to add the path of the referenced XML Schema file to the root element of the XML output.
The path allows you to define where the schema file, referenced by the XML instance file, is to
be located. This ensures that the output instance can be validated at the mapping destination
when the mapping is executed. You can enter an http:// address as well as an absolute, or
relative path in this field.
Altova MapForce 2011
© 2011 Altova GmbH
MapForce user interface
5.3
Output tab
63
Output tab
The result of the mapping is immediately presented in the Output tab, using the Altova XSLT
engine.
Depending on the target component of your mapping, the Output tab may show different things:
XML Schema/document as target:
The screen shot below shows the output of the DB_CompletePO.mfd mapping available in the
...\MapForceExamples folder. An XML Schema/document, as well as a database are used as
source components in this mapping.
The resultant XML file can be saved by clicking the Save icon, and validated against the
referenced schema by clicking the validate icon in the icon bar.
Hotkeys for the Output window (keyboard and numeric key pad):
CTRL and "+" zoom in on the text
CTRL and "-" zoom out of the text
CTRL and "0" resets the zoom factor to standard
CTRL and mouse wheel forward / backward achieve the same zoom in/out effect.
To save the XML, or output data from the Output tab:
1. Click the Output tab to preview the mapping result.
2. Click the "Save generated output" icon
be saved.
, and specify where you want the result to
If the target is an XML/Schema file:
© 2011 Altova GmbH
Altova MapForce 2011
64
MapForce user interface
·
Output tab
The Save generated output icon is active. Click it to save the output.
If the target is a Database:
·
The Run SQL-script icon
data.
is active. Click it to update, insert, or delete the database
To search for specific data in the Output tab:
· Select the menu option Edit | Find, or hit the CTRL+F keyboard keys.
The Find dialog box allows you to specify the search options in great detail, and also
supports regular expressions.
Altova MapForce 2011
© 2011 Altova GmbH
MapForce user interface
5.4
Functions and libraries
65
Functions and libraries
The Libraries pane displays the available libraries for the currently selected programming
language, as well as the individual functions of each library. Functions can be directly dragged
into the Mapping tab. Once you do this, they become function components.
XSLT Selected
The standard core and xslt libraries are always loaded when you start MapForce, and do not
need to be added by the user. The Core library is a collection of functions that can be used to
produce all types of output: XSLT. The other libraries (XSLT, XSLT2, XPath2, Lang etc.)
contain functions associated with each separate type of output.
Selecting:
XSLT, enables the core and XSLT functions (XPath 1.0 and XSLT 1.0 functions).
XSLT2, enables the core, XPath 2.0, and XSLT 2.0 functions.
XPath 2.0 restrictions:
Several XPath 2.0 functions dealing with sequences are currently not available.
To find a function in the Library window:
1. Click into the Libraries window to make it active and enter the characters you are
looking for, e.g. "lo".
© 2011 Altova GmbH
Altova MapForce 2011
66
MapForce user interface
Functions and libraries
XSLT Selected
All functions containing these characters are now shown in the Library window, each
within its respective group.
3. Click the down-arrow and select "Include function descriptions", if you want to include
the text of the function descriptions in the function search.
Note: pressing the Esc key cancels the filtering function in the window. Clicking the "x"
icon has the same effect.
To use a function in Mapping window:
1. First select the programming language you intend to generate code for, by clicking
one of the output icons in the title bar: XSLT/XSLT2, .
The functions available in that language are now visible in the Libraries window. The
expand and contract icons show, or hide the functions of that library.
2. Click the function name and drag it into the Mapping window.
3. Use drag and drop to connect the input and output parameters to the various icons.
Note that placing the mouse pointer over the "result = xxx" expression in the library
pane, displays a ToolTip describing the function in greater detail.
Function tooltips:
Explanatory text (visible in the libraries pane) on individual functions, can be toggled on/off by
clicking the "Show tips" icon
in the title bar. Placing the mouse pointer over a function
header, displays the information on that function.
Altova MapForce 2011
© 2011 Altova GmbH
MapForce user interface
Functions and libraries
67
To add new function libraries:
MapForce allows you to create and integrate your own function libraries, please see the
sections: Adding custom XSLT 1.0 functions, Adding custom XSLT 2.0 functions and
User-defined functions for more information.
Please note:
custom functions/libraries can be defined for XSLT and XSLT 2.
Extendable functions
Several functions available in the function libraries are extendable: for e.g. the concat,
"logical-and", "logical-or", and IF-ELSE functions. The parameters of these types of function can
be inserted/appended and deleted at will.
Clicking the "plus" icon inserts or appends the same type of parameter, while clicking the check
mark deletes the parameter.
Please note: "dropping" a connector on the "plus" symbol, automatically inserts/appends the
parameter and connects it.
The IF test parameters, of the IF-Else function can be extended in the same way.
© 2011 Altova GmbH
Altova MapForce 2011
68
MapForce user interface
5.4.1
Function context menu
Functions and libraries
Function context menu:
Right clicking a function in the Mapping window, opens the context window.
Priority Context
When applying a function to different items in a schema, MapForce needs to know what the
context node will be. All other items are then processed relative to this one.
This is achieved by designating the item (or node) as the priority context. A circle appears
around the icon so designated. Please see Priority Context in the Reference section, for an
example.
Show Library in Function Header
Displays the library name in the function component.
Replace Component with Internal Function Structure
Replaces the user-defined component/function with its constituent parts, not available for
functions.
Cut/Copy/Paste/Delete
The standard MS Windows Edit commands, allow you to cut, copy etc., any components or
functions visible in the mapping window. All connectors will be retained except for those which
would have to be replaced.
Properties
Not available for functions.
Altova MapForce 2011
© 2011 Altova GmbH
Chapter 6
Methods of mapping data (Standard / Mixed / Copy All)
70
Methods of mapping data (Standard / Mixed / Copy All)
6
Methods of mapping data (Standard / Mixed / Copy All)
MapForce supports various methods of mapping data:
Target Driven (Standard)
Standard mapping means the normal method of mapping used in MapForce, i.e. the output
depends on the sequence of the target nodes. Please see Source-driven / mixed content vs.
standard mapping for more information.
·
·
Mixed content text node content is not supported/mapped.
The sequence of child nodes is dependent on the target schema file.
Source driven / mixed content mapping
Mixed content mapping enables you to automatically map text and child nodes in the same
sequence that they appear in the XML source file.
·
·
Mixed content text node content is supported/mapped.
The sequence of child nodes is dependent on the source XML instance file.
Copy All mapping
This type of connection allow you to automatically connect all identical items in source and
target components.
Depending on the source and target type:
·
all source child items are copied to the target component, if either the source and
target types are identical, or if the target type is xs:anyType
·
if the source and target types are not identical, and if the target type is not
xs:anyType, the source data is transferred/mapped to the respective target items of the
same name and the same hierarchy level. If the names of the target items differ, then
the target item is not created.
Connectors and their properties:
· Clicking a connector highlights it in red.
· Hitting the Del key, while a connector is highlighted, deletes it immediately.
· Right clicking a connector, opens the connector context menu.
· Double clicking a connector, opens the Connection Settings dialog box.
Viewing connectors
MapForce allows you to selectively view the connectors in the mapping window.
Show selected component connectors
Switches between showing:
·
·
all mapping connectors in black, or
those connectors relating to the currently selected component in black. Other
connectors appear dimmed.
Show connectors from source to target
Switches between showing:
·
·
connectors that are directly connected to the currently selected component, or
connectors linked to the currently selected component, originating from source and
Altova MapForce 2011
© 2011 Altova GmbH
Methods of mapping data (Standard / Mixed / Copy All)
71
terminating at the target components.
© 2011 Altova GmbH
Altova MapForce 2011
72
Methods of mapping data (Standard / Mixed / Copy All)
6.1
Source driven / mixed content mapping
Source driven / mixed content mapping
MapForce supports source driven / mixed content mapping. Source driven / mixed content
mapping enables you to automatically map text and child nodes in the same sequence that they
appear in the XML source file.
Source-driven mapping can, of course, also be applied to XML schema complexType items if
you wish. Child nodes will then be mapped according to their sequence in the XML source file.
Source driven / mixed content mapping supports:
·
·
XML schema complexTypes as source components,
XML schema complexTypes of type mixed content, i.e. mixed=true, as source
components,
·
XML schema complexTypes (including mixed content), as target components
Note: CDATA sections are treated as text.
The image below shows an example of mixed content mapping. The para element is of mixed
content, and the connector is shown as a dotted line to highlight this. The text() node contains
the textual data and needs to be mapped for the text to appear in the target component.
Right clicking a connector and selecting Properties, allows you to annotate, or label the
connector. Please see section "Connection" in the Reference section for more information.
Altova MapForce 2011
© 2011 Altova GmbH
Methods of mapping data (Standard / Mixed / Copy All)
Source driven / mixed content mapping
73
The files used in the following example (Tut-Orgchart.mfd) are available in the
...\MapForceExamples\Tutorial\ folder.
The image below shows the content model of the Description element (Desc) of the
Tut-OrgChart.xsd schema file. This definition is identical in both the source and target
schemas used in this example.
Content model of para element:
·
·
·
·
para is a complexType with mixed = true, of type TextType.
bold and italic elements are both of type xsd:string, they have not been defined as
recursive in this example. i.e. neither bold, nor italic are of type "TextType".
bold and italic elements can appear any number of times in any sequence within para.
any number of text nodes can appear within the para element, interspersed by any
number of bold and italic elements.
Source XML instance:
A portion of the Tut-OrgChart.XML file used in this section is shown below. Our area of
concern is the mixed content element "para", along with it's child nodes "bold" and "italic".
Please note that the para element also contains a Processing Instruction (sort alpha-ascending)
as well as Comment text (Company details...) which can also be mapped, see "mixed content
settings".
Please note the sequence of the text and bold/italic nodes of Nanonull., Inc in the XML instance
file, they are:
<para> The company...
<bold>Vereno</bold>in 1995 ...
<italic>multi-core...</italic>February 1999
© 2011 Altova GmbH
Altova MapForce 2011
74
Methods of mapping data (Standard / Mixed / Copy All)
Source driven / mixed content mapping
<bold>Nano-grid.</bold>The company ...
<italic>offshore...</italic>to drive...
</para>
Mapping
The initial state of the mapping is shown below.
Output of above mapping:
The result of the initial mapping is shown below: Organization Chart as well as the individual
office names have been output.
Altova MapForce 2011
© 2011 Altova GmbH
Methods of mapping data (Standard / Mixed / Copy All)
6.2
Mapping mixed content text() nodes
75
Mapping mixed content text() nodes
Creating mixed content connections between items:
1. Select the menu option Connection | Auto Connect Matching Children to activate
this option, if it is not currently activated.
2. Connect the para item in the source schema, with the para item in the target schema.
A message appears, asking if you would like MapForce to define the connectors as
source driven.
3. Click Yes to create a mixed content connection.
Please note:
Para is of mixed content, and makes the message appear at this point. The
mixed-content message also appears if you only map the para items directly, without
having the autoconnect option activated.
All child items of para have been connected. The connector joining the para items is
displayed as a dotted line, to show that it is of type mixed content.
4. Click the Output tab to see the result of the mapping.
© 2011 Altova GmbH
Altova MapForce 2011
76
Methods of mapping data (Standard / Mixed / Copy All)
5. Click the word Wrap icon
the Output window.
Mapping mixed content text() nodes
in the Output tab icon bar, to view the complete text in
The mixed content text of each office description has been mapped correctly; the text,
as well as the bold and italic tag content, have been mapped as they appear in the
XML source file.
6. Switch back to the Mapping view.
Removing text nodes from mixed content items:
1. Click the text() node connector and press Del. to delete it.
Altova MapForce 2011
© 2011 Altova GmbH
Methods of mapping data (Standard / Mixed / Copy All)
Mapping mixed content text() nodes
77
2. Click the Output tab to see the result of the mapping.
Result:
· all text nodes of the para element have been removed.
· mapped bold and italic text content remain
· the bold and italic item sequence still follows that of the source XML file!
© 2011 Altova GmbH
Altova MapForce 2011
78
Methods of mapping data (Standard / Mixed / Copy All)
6.3
Mixed content - connection settings
Mixed content - connection settings
Mixed content settings:
· Right click the para connector and select Properties.
This opens the Connection Settings dialog box in which you can define the specific
(mixed content) settings of the current connector. Note that unavailable options are
greyed out.
Please note that these settings also apply to complexType items which do not have
any text nodes!
Target Driven (Standard)
Changes the connector type to Standard mapping, please see: "Source-driven / mixed content
vs. standard mapping" for more information.
Copy-all (Copy child items)
Changes the connector type to Copy-all and automatically conntects all identical items in the
source and target components. Please see Copy-all connections for more information.
Source Driven (mixed content)
Changes the connector type to source driven / mixed content, and enables the selection of
additional elements to be mapped. The additional elements have to be child items of the
mapped item in the XML source file, to be able to be mapped.
Altova MapForce 2011
© 2011 Altova GmbH
Methods of mapping data (Standard / Mixed / Copy All)
Mixed content - connection settings
79
Activating the Map Processing Instructions and/or Map Comments check boxes enables you
to include those data in the output file.
Please note:
CDATA sections are treated as text.
Annotation Settings - Commenting mappings / connectors
Individual connectors can be labeled allowing you to comment your mapping in great detail.
1. Enter the name of the currently selected connector in the Description field.
This enables all the options in the Annotation Settings group.
2. Use the remaining groups to define the position and alignment of the label.
3. Activate the Show annotations icon
© 2011 Altova GmbH
in the icon bar to see the annotation text.
Altova MapForce 2011
80
Methods of mapping data (Standard / Mixed / Copy All)
Mixed content - connection settings
Note:
If the Show annotations icon is inactive, you can still see the annotation text if you place
the mouse cursor over the connector. The annotation text will appear in a popup.
Altova MapForce 2011
© 2011 Altova GmbH
Methods of mapping data (Standard / Mixed / Copy All)
6.4
Mixed content example
81
Mixed content example
The following example is available as "ShortApplicationInfo.mfd" in the
...\MapForceExamples folder.
A snippet of the XML source file for this example is shown below.
The mapping is shown below. Please note that:
·
·
·
·
The "SubSection" item connector is of mixed content, and is mapped to the Description
item in the target XML/schema.
The text() nodes are mapped to each other
Trademark text is mapped to the Bold item in the target
Keyword text is mapped to the Italic item in the target
Mapping result:
· The mixed content text of each description has been mapped correctly; the text, as well
as the bold and italic tag content, have been mapped as they appear in the XML source
file.
© 2011 Altova GmbH
Altova MapForce 2011
82
Methods of mapping data (Standard / Mixed / Copy All)
Altova MapForce 2011
Mixed content example
© 2011 Altova GmbH
Methods of mapping data (Standard / Mixed / Copy Source-driven/mixed
All)
content Vs. standard mapping
6.5
83
Source-driven/mixed content Vs. standard mapping
This section describes the results when defining standard mappings (or using standard
connectors) on mixed content nodes. The files used in the following example (
Tut-Orgchart.mfd) are available in the ...\MapForceExamples\Tutorial\ folder.
Creating standard connections between mixed content items:
1. Create a connector element between the two para items.
A message appears, asking if you would like MapForce to define the connectors as
source driven.
2. Click No to create a standard mapping.
2. Click the Output tab to see the result of the mapping.
Result:
·
·
·
·
Text() content is supported/mapped.
The start/end tags of the child nodes, bold and italic, are removed from the text node.
The child nodes appear after the mixed content node text.
The sequence of child nodes depends on the sequence in the target XML/schema file.
i.e.:
For each para element, map the text() node, then all bold items, finally all italic items.
This results in the child item sequence shown above: bold, bold - italic, italic. The
content of each item is mapped if a connector exists.
© 2011 Altova GmbH
Altova MapForce 2011
84
Methods of mapping data (Standard / Mixed / Copy All)
6.6
Copy-all connections
Copy-all connections
This type of connection allow you to simplify your workspace and automatically connect all
identical items in source and target components, meaning that, depending on the source and
target type:
·
all source child items are copied to the target component, if either the source and
target types are identical, or if the target type is xs:anyType
·
if the source and target types are not identical, and if the target type is not
xs:anyType, the source data is transferred/mapped to the respective target items of the
same name and the same hierarchy level. If the names of the target items differ, then
the target item is not created.
·
Note that only the names of the child items, but not their individual types, are
compared/matched.
Currently Copy-all connections are supported:
·
between XML schema complex types, and
·
between complex components (XML schema) and complex user-defined
functions/components containing the same corresponding complex parameters, please
see "Complex output components - defining" for an example.
The example below shows these connectors using the MarketingAndDailyexpenses.mfd file
in the ...\MapForceExamples folder.
To define a Copy-all connection:
1. Right click an existing connector, e.g. the Person connector, and select "Copy-all" from
the context menu.
A prompt appears reminding you that the target connectors will be deleted.
2. Click OK to create Copy-all connectors.
Altova MapForce 2011
© 2011 Altova GmbH
Methods of mapping data (Standard / Mixed / Copy All)
Copy-all connections
85
All connectors to the target component, and all source and target items with identical
names are created.
Please note:
· When the existing target connections are deleted, connectors from other source
components, or other functions are also deleted.
·
This type of connection cannot be created between an item and the root element of a
schema component.
·
Individual connectors cannot be deleted, or reconnected from the Copy-all group, once
you have used this method.
Copy-all connections and user-defined functions
When creating Copy-all connections between a schema and a user-defined function parameter,
the two components must be based on the same schema! It is not necessary that they both
have the same root elements however. Please see "Complex output components - defining" for
an example.
Copy-all connections and filters
Copy-all connections can also be created through filter components if the source component:
·
·
·
consists of structured data, meaning a schema component.
receives data through a complex output parameter of a user-defined function, or Web
service.
receives data through another filter component.
Only the filtered data is passed on to the target component.
© 2011 Altova GmbH
Altova MapForce 2011
86
Methods of mapping data (Standard / Mixed / Copy All)
Copy-all connections
To define a copy-all connection through a filter component:
1. Right click the filter output connector i.e. the right hand on-true/on-false connector.
2. Select Copy-all (Copy child items) from the context menu.
The copy-all connector between items of the same name are created.
Please note:
To change the connector back to a different type, make sure you right click connector
on the output side of the filter. The left hand connector cannot be used to change the
connection type because the on-true and on-false connectors might have different
settings.
To resolve/delete copy-all connectors:
1. Connect any item to a child item of the copy-all connection at the target component.
You are notified that only one connector can exist at the target item. Click Replace to
replace the connector.
2. Click the Resolve copy-all connection button in the next message box that opens.
The copy-all connection is replaced by individual connectors to the target component.
Altova MapForce 2011
© 2011 Altova GmbH
Methods of mapping data (Standard / Mixed / Copy All)
6.7
Moving connectors
87
Moving connectors
Moving connectors and the effect on child connectors
When moving a parent connector to a different parent connector item, MapForce automatically
matches identical child connections under the new location of the connector. This is not the
same as the auto-connect child option, as it uses different rules to achieve this.
Uses:
·
·
You have an exisiting mapping and then change the root element of the target schema.
This would normally force you to remap all descending connectors manually.
You have two components with several xsi:type (or duplicate) nodes in each, and you
move a parent connector to a different component.
This example uses the Tut-ExpReport.mfd file available in the ...\MapForceExamples\Tutorial
folder.
If the Company root element of the target schema, is changed to Company-EU then a
"Changed files" prompt appears in MapForce.
1. Click the Reload button to reload the updated Schema.
You are now presented with multiple missing nodes as the root element has changed.
2. Click on the "Select new root element" link at the top of the component.
© 2011 Altova GmbH
Altova MapForce 2011
88
Methods of mapping data (Standard / Mixed / Copy All)
Moving connectors
3. Select the updated root element, Company-EU and click OK to confirm.
The Company-EU root element is now visible at the top of the component.
4. Click the connector on the Company item and use drag-and-drop to drop it on the new
Company-EU root element.
A prompt appears asking which connectors you want to move.
5. Click the "Include descendent connections" button if you want to map the child
connectors.
The "missing" item nodes have been removed and all connectors have been mapped to
the correct child items under the new root element.
Altova MapForce 2011
© 2011 Altova GmbH
Methods of mapping data (Standard / Mixed / Copy All)
Moving connectors
89
Please note:
If the item/node you are mapping to has the same name (as the source node) but is in
a different namespace, then the prompt will contain an additional button "Include
descendants and map namespace".
Clicking this button moves the child connectors of the same namespace as the source
parent node, to the same child nodes under the different namespace node. I.e. If the
parent nodes only differ in their namespace, then the child nodes may only differ in the
same way, if they are to be mapped automatically.
© 2011 Altova GmbH
Altova MapForce 2011
Chapter 7
Global Resources
92
Global Resources
7
Global Resources
Global resources are a major enhancement in the interoperability between products of the
Altova product line, and are currently available in the following Altova products: XMLSpy,
MapForce, StyleVision and DatabaseSpy. Users of the Altova Mission kits have access to the
same functionality in the respective products.
General uses:
· Workflows can be defined that use various Altova applications to process data.
· An application can invoke a target application, initiate data processing there, and route
the data back to the originating application.
· Defining input and output data, file locations , as global resources.
· Switching between global resources during runtime to switch between development or
deployment resources.
· What-if scenarios for QA purposes.
The default location of the global resource definitions file, GlobalResources.xml, is c:
\Documents and Settings\UserName\My Documents\Altova\. This is the default location for all
Altova applications that can use global resources. Changes made to global resources are thus
automatically available in all applications. The file name and location can be changed please
see Global Resources - Properties for more information.
General mechanism:
· Global resources are defined in an application and automatically saved.
· Global resources are assigned to components whose data you intend to be variable.
· The global resource is invoked / activated in an application, allowing you to switch
resources at runtime.
This section will describe how to define and use, global resources using existing mappings
available in the ...\MapForceExamples\Tutorial\ folder.
To activate the Global Resources toolbar:
Select the menu option Tools | Customize | click the Toolbar tab and activate the Global
Resources check box. This displays the global resources tool bar.
The combo box allows you to switch between the various resources, a "Default" entry is always
available.
Clicking the Global Resources icon
opens the Global Resources dialog box (alternatively
Tools | Global Resources).
Altova MapForce 2011
© 2011 Altova GmbH
Global Resources
7.1
Global Resources - Files
93
Global Resources - Files
Global Resources in MapForce:
· Any input/output components files can be defined as global resources, e.g. XML, XML
Schema, files.
Aim of this section:
· To make the source component input file, mf-ExpReport, a global resource.
· To switch between the two XML files that supply its input data at runtime, and check
the resulting XML output in the Output preview tab.
This section uses the Tut-ExpReport.mfd file available in the ...\MapForceExamples
\Tutorial\ folder.
© 2011 Altova GmbH
Altova MapForce 2011
94
Global Resources
Global Resources - Files
7.1.1
Defining / Adding global resources
Defining / Adding a global resource file
1. Click the Global Resource icon
to open the dialog box.
This is the state of an empty global resources file.
2. Click the Add button and select File from the popup.
3. Enter the name of the Resource alias e.g. MultiInput.
4. Click the Open folder icon and select the XML file that is to act as the "Default" input file
e.g. mf-ExpReport.xml.
5. Click the Add button
of the Configurations group, to add a new configuration to the
current Alias. Note that the Copy configuration icon
configuration and save it under a new name.
Altova MapForce 2011
, allows you to copy a selected
© 2011 Altova GmbH
Global Resources
Global Resources - Files
95
6. Enter a name for the configuration, Multi2nd, and click OK to confirm.
Multi2nd has now been added to the Configurations list.
7. Click the Open folder icon again and select the XML file that is to act as the input file for
the multi2nd configuration e.g. mf-ExpReport2.xml.
8. Click OK to complete the definition of the resource.
The MultiInput alias has now been added to the Files section of the global resources.
Placing the mouse cursor over an alias entry, opens a tooltip showing its defintion.
© 2011 Altova GmbH
Altova MapForce 2011
96
Global Resources
Global Resources - Files
9. Click OK to confirm.
This concludes the definition part of defining global resources. The next step is
Assigning a global resource to a component.
Altova MapForce 2011
© 2011 Altova GmbH
Global Resources
7.1.2
Global Resources - Files
97
Assigning a global resource
Assigning global resources to a component
We now have to assign the global resource to the component that is to make use of it.
1. Double click the mf-ExpReport component and click the Browse button next to the
Input XML-Instance field.
This opens the "Choose XML Instance file" dialog box.
2. Click the Switch to Global Resources button at the base of the dialog box.
3. Click the resource you want to assign, MultiInput in this case, and click OK.
The Input XML-Instance field now contains a reference to a resource i.e. altova://
file_resource/MultiInput.
© 2011 Altova GmbH
Altova MapForce 2011
98
Global Resources
Global Resources - Files
4. Click OK to complete the assignment of a resource to a component.
The next step is Using / activating a global resource.
Altova MapForce 2011
© 2011 Altova GmbH
Global Resources
7.1.3
Global Resources - Files
99
Using / activating a global resource
Using / activating a global resource
At this point the previously defined Default configuration for the MultiInput Alias is active. You
can check this by noting that the entry in the Global Resources icon bar is "Default".
1. Click the Output tab to see the result of the mapping.
2. Click the Mapping tab to return to the mapping view.
3. Click the global resources combo box select Multi2nd from the combo box.
4. Click the Output tab to see the new result.
The mf-ExpReport2.xml file is now used as the source component for the mapping, and
produces different output.
© 2011 Altova GmbH
Altova MapForce 2011
100
Global Resources
Global Resources - Files
Note:
The currently active global resource (multi2nd in the global resources toolbar)
determines the result of the mapping. This is also the case when you generate code.
Altova MapForce 2011
© 2011 Altova GmbH
Global Resources
7.2
Global Resources - Folders
101
Global Resources - Folders
Folders can also be defined as a global resource, which means that input components can
contain files that refer to different folders, for development and release cycles for example.
Defining folders for output components is not really useful in MapForce, as you are always
prompted for the target folders when generating XSLT or code for other programming
languages.
The mapping file used in this section is available as "global-folder.mfd" in the ...
\MapForceExamples\Tutorial\ folder.
Defining / Adding global resource folders
1. Click the Global Resource icon
to open the dialog box.
2. Click the Add button and select Folder from the popup.
3. Enter the name of the Resource alias e.g. Dev_Release.
4. Click the Open folder icon and select the "Default" input folder, ...\MapForceExamples.
5. Click the Add button
of the Configurations group, to add a new configuration to the
current Alias, and enter a name for it e.g. Release. Note that the Copy configuration
icon
, allows you to copy a selected configuration and save it under a new name.
6. Click the Open folder icon and select the Release input folder, ...\MapForceExamples
\Tutorial.
7. Click OK to finish the global folder definition.
Assigning the global resource folders:
1. Double click the ExpReport component and click the Browse button next to the Input
XML File field.
© 2011 Altova GmbH
Altova MapForce 2011
102
Global Resources
Global Resources - Folders
This opens the "Choose XML Instance file" dialog box.
2. Click the Switch to Global Resources button at the base of the dialog box.
3. Click the resource you want to assign, Dev_Release in this case, and click OK.
The "Open..." dialog appears.
4. Select the file name that is to act as both the Development and Release resource file
in each of the folders, e.g. ExpReport.xml and click OK to finish assigning the resource
folder.
Altova MapForce 2011
© 2011 Altova GmbH
Global Resources
Global Resources - Folders
103
Note that this file is available in both directories but has different content.
Changing the resource folder at runtime:
1. Click the Output tab to see the result of the transformation.
Note that this is the Default configuration/folder .../MapforceExamples.
2. Click the Mapping tab to return to the mapping window.
3. Click the Global Resource combo box and select the "Release" entry.
3. Click the Output button to see the result using the Release global resource.
The output from the "Release" folder .../MapforceExamples/Tutorial is now displayed.
© 2011 Altova GmbH
Altova MapForce 2011
104
Global Resources
Global Resources - Application workflow
7.3
Global Resources - Application workflow
The aim of this section is to create a workflow situation between two Altova applications.
Workflow is initiated in XMLSpy which starts MapForce and passes the generated XML file
output back to XMLSpy for further processing.
This mapping uses two output components to produce two types of filtered output; Travel and
Non-travel expenses of the expense report input file. This section uses the Tut-ExpReportmulti.mfd mapping file available in the ...\MapForceExamples\Tutorial\ folder.
1.
2.
3.
4.
Click the Global Resource icon
to open the dialog box.
Click the Add button and select File from the popup.
Enter the name of the Resource alias e.g. MultiOutput2Spy
Click the "Result of MapForce Transformation" radio button and select the TutExpReport-multi.mfd mapping.
Altova MapForce 2011
© 2011 Altova GmbH
Global Resources
Global Resources - Application workflow
105
MapForce analyzes the mapping and displays the input and output files in separate list
boxes. Placing the mouse cursor over a path, displays the full path (and file name) in a
tooltip.
5. Click the top radio button entry in the Outputs section, if not already selected.
Note that the output file name is ExpReport-Target.xml and that we are currently
defining the Default configuration.
6. Click the
icon to define the new location of the output file, and select Browse... from
the popup menu.
7. Enter the new output location e.g. C:\Temp and click the Save button. This location can
differ from the location defined in the component settings.
© 2011 Altova GmbH
Altova MapForce 2011
106
Global Resources
Global Resources - Application workflow
8. Click the Add button
of the Configurations group (of this dialog box), to add a new
configuration to the resource alias.
9. Enter the name of the configuration, e.g. Output2, and click the lower radio button of
the Outputs listbox. Note that the output file name is SecondXML.xml.
10. Click the "Save as" icon
to define the new location of the output file e.g. C:\Temp.
Note: clicking the "Choose another Global Resource... in the popup, allows you to
save the MapForce output as a global resource. I.e. the output is stored to a file that the
global resource physically points to/references.
11. Click OK to save the new global resources.
The new resource alias MultiOutput2Spy has been added to the Global Resources
definition file.
Altova MapForce 2011
© 2011 Altova GmbH
Global Resources
Global Resources - Application workflow
107
12. Click OK to complete the definition phase.
© 2011 Altova GmbH
Altova MapForce 2011
108
Global Resources
7.3.1
Start application workflow
Global Resources - Application workflow
This section shows how the Global Resource is activated in XMLSpy and how the resulting
MapForce transformation is routed back to it.
1. Start XMLSpy and shut down MapForce, if open, to get a better view of how the two
applications interact.
2. Select the menu option Tools | Global Resources in XMLSpy.
3. Select the MultiOutput2Spy entry, and click the View button.
A message box stating that MapForce is transforming appears, with the result of the
transformation appearing in the Text view window.
Altova MapForce 2011
© 2011 Altova GmbH
Global Resources
Global Resources - Application workflow
109
Note:
· The currently selected configuration is "Default".
· The name of the resource alias is in the application title bar altova://file_resource/
MultiOutput2Spy.
· The output file has been opened as "Untitled1.xml" for further processing.
· The ExpReport-Target.xml file has been copied to the C:\Temp folder.
To retrieve the non-travel expenses output:
1. Click the Global Resources combo box and select "Output2".
A notification message box opens.
2. Click Reload to retrieve the second output file defined by the resource.
© 2011 Altova GmbH
Altova MapForce 2011
110
Global Resources
Global Resources - Application workflow
The result of the transformation appears in the Text view window and overwrites the
previous Untitled1.xml file.
Note:
· The currently selected configuration is "Output2"
· The output file has been opened as "Untitled1.xml" for further processing.
· The SecondXML.xml file has been copied to the C:\Temp folder.
Altova MapForce 2011
© 2011 Altova GmbH
Global Resources
7.4
Global Resources - Properties
111
Global Resources - Properties
The Global Resources XML File
Global resources definitions are stored in an XML file. By default, this XML file is called
GlobalResources.xml, and it is stored in the folder C:\Documents and Settings
\<username>\My Documents\Altova\. This file is set as the default Global Resources XML
File for all Altova applications. As a result, a global resource defined in any application will be
available to all Altova applications—assuming that all applications use this file.
You can also re-name the file and save it to any location. You can therefore have multiple
Global Resources XML files. However, only one of these Global Resources XML File can be
active, per application, at one time, and only the definitions contained in this file will be available
to the application.
To make the Global Resources XML file active, Browse button of the "Definitions file" field and
select the one you want to use from the "Open..." dialog box.
Managing global resources: adding, editing, deleting
In the Global Resources dialog, you can add a global resource to the selected Global
Resources XML File, or edit or delete a selected global resource. The Global Resources XML
File organizes the aliases you add into the following sections: files, folders.
To add a global resource:
Click the Add button and define the global resource in the Global Resource dialog that pops up.
After you define a global resource and save it, the global resource (or alias) is added to the list
of global definitions in the selected Global Resources XML File.
To edit a global resource:
Select it and click Edit. This pops up the Global Resource dialog, in which you can make the
necessary changes.
To delete a global resource:
Select it and click Delete.
To view the result of an application workflow:
If the calling application e.g. XMLSpy, calls another application e.g. MapForce, then a View
© 2011 Altova GmbH
Altova MapForce 2011
112
Global Resources
Global Resources - Properties
button is available in the Manage Global Resources dialog box.
Clicking the View button shows the affect of the currently selected global resource in the callling
application. Please see Global Resources - Application workflow for an example.
To save modifications made in the Managing Global Resources dialog box:
Having finished adding, editing, or deleting, make sure to click OK in the Global Resources
dialog to save your modifications to the Global Resources XML File.
Note: Alias resource names must be unique within each of the Files, Folders. You can however
define an identical alias name in two different sections, e.g. a multiInput alias can exist in the
Files section as well as in the Folders section.
Selecting Results of MapForce transformations as a global resource
In a MapForce transformation that has multiple outputs, you can select which one of the output
files should be used for the global resource by clicking its radio button.
The output file that is generated by the mapping can be saved as:
·
a global resource via the Choose another Global Resource entry in the popup, visible
as altova://file_resource/MF_output. The output is stored to a file that the global
resource physically points to/references.
·
a file via the
icon, shown as C:\TEMP\Second.xml.
If neither of these options is selected, a temporary XML file is created when the global
resource is used.
Determining which resource is used at runtime
There are two application-wide selections that determine what global resources can be used
and which global resources are actually used at any given time:
·
The active Global Resources XML File is selected in the Global Resource dialog. The
active Global Resources XML File can be changed at any time, and the global-resource
definitions in the new active file will immediately replace those of the previously active
file.
The active Global Resources XML File therefore determines: (i) what global resources
can be assigned, and (ii) what global resources are available for look-up (for example, if
a global resource in one Global Resource XML File is assigned but there is no global
Altova MapForce 2011
© 2011 Altova GmbH
Global Resources
Global Resources - Properties
113
resource of that name in the currently active Global Resources XML File, then the
assigned global resource (alias) cannot be looked up).
·
The active configuration is selected via the menu item Tools | Active Configuration or
via the Global Resources toolbar. Clicking this command (or dropdown list in the
toolbar) pops up a list of configurations across all aliases.
Selecting a configuration makes that configuration active application-wide. This means
that wherever a global resource (or alias) is used, the resource corresponding to the
active configuration of each used alias will be loaded.
The active configuration is applied to all used aliases. If an alias does not have a
configuration with the name of the active configuration, then the default configuration
of that alias will be used. The active configuration is not relevant when assigning
resources; it is significant only when the resources are actually used.
Changing resources / configurations
Resources can be switched by selecting a different configuration name. This can be done in two
ways:
·
When you hover over the menu command Tools | Active Configuration, a submenu
with a list of all configurations in the Global Resources XML File appears. Select the
required configuration from the submenu.
·
In the combo box of the Global Resources toolbar, select the required configuration.
The Global Resources toolbar can be toggled on and off with the menu command
Tools | Customize, then click the Toolbar tab and enable/disable the Global
resources check box.
© 2011 Altova GmbH
Altova MapForce 2011
Chapter 8
Dynamic input/output files per component
116
Dynamic input/output files per component
8
Dynamic input/output files per component
MapForce is able to process multiple input / output files per component, and can thus process
all the files in a directory, or a subset of them, by using wildcard characters in the input
component.
The example in the tutorial shows how a source component processes two XML input files, and
how the target component outputs two XML documents.
Multiple input / output files can be defined for the following components:
· XML files
Please take note of the File: item at the top of the abovementioned components:
·
The File:mf-ExpReport.xml item of mf-ExpReport, displays the Input XML file entry.
This is automatically filled when you assign an XML instance file to an XML schema file.
(If an output file has been defined then the output file name will be also be displayed.)
·
The File: (default) item of ExpReport-Target shows that an output instance file was not
assigned to the XML schema component when it was inserted. I.e. the Output XML file
field is empty. A default value will therefore be used when the mapping executes.
Dynamic file name support is activated by mapping a string containing a file name to
the File item. If the component is used as an input component, the file name may
contain wildcards. See also: relative path handling.
·
The File: <dynamic> item is shown when there is a connection to the File item, i.e.
multiple files are now supported.
·
The replace-fileext function converts the .xml extention to .out for the dynamic target
files.
Dynamic/multi-file and wildcard support for MapForce supported languages:
Target
language
XSLT 1.0
XSLT 2.0
*
Dynamic input file
name
*
*
Wildcard support for
input file name
not supported by XSLT 1.0
*(1)
Dynamic output file
name
not supported by XSLT 1.0
*
supported
(1) Uses the fn:collection function. The implementation in the Altova XSLT 2.0 and
XQuery engines resolves wildcards. Other engines may behave differently.
Altova MapForce 2011
© 2011 Altova GmbH
Dynamic input/output files per component
117
Wildcards * and ? are resolved when entered in the Component Settings dialog box and
also when mapping a string to the File: name node.
To transform XSLT 1.0/2.0 and XQuery code using AltovaXML, please see
© 2011 Altova GmbH
Altova MapForce 2011
118
Dynamic input/output files per component
8.1
Dynamic file names - input / output
Dynamic file names - input / output
By mapping file names dynamically inside the mapping, you can:
·
·
·
·
generate a mapping application where the input and output file names can be defined at
runtime
convert a set of files to another format (many-to-many)
split a large file (or database) into smaller sections/parts
merge multiple files into one large file (or load them into a database)
To process multiple input files, you can do one of the following:
· Enter a file path with wildcards (* or ?) as input file in the Component Settings dialog
box. All matching files will be processed. The example below uses the ? wildcard
character in the Input XML file field to map all files starting with mf-ExpReport with one
following character, of which there are two in the ...\Tutorial folder.
·
Map a sequence of strings to the File node of the source component. Each string in the
sequence represents one file name. The strings may also contain wildcards, which are
automatically resolved.
A sequence of file names can be supplied by:
· An XML file
Preview of dynamic input / output mappings
Clicking the Output tab displays the mapping result in a preview window. If the mapping
produces multiple output files, as shown below, Preview 1 of 2, each file has its own numbered
pane in the Output tab. Click the arrow buttons to see the individual output files.
Altova MapForce 2011
© 2011 Altova GmbH
Dynamic input/output files per component
Click the Save all generated outputs icon
Dynamic file names - input / output
119
, to save the generated output files you see here.
Multi input / single output - merging input files
Multiple input files can be merged into a single output file if the connector between the two
File: items is removed, while the source component still accesses multiple files e.g. per
wildcard "?". While the source component can take multiple files, the output component cannot.
The multiple source files are thus appended in the target document.
Multi input / multi output
To map multiple files n:n to multiple target files, you need to generate unique output file names.
In some cases, the output file names can be derived from strings in the input data, and in other
cases it is useful to derive the output file name from the input file name, e.g. by changing the file
extension.
The full path name of the currently processed file is available by connecting the output icon of
the File node, e.g. to concat for adding a new file extension.
Please note:
Avoid simply connecting the File: nodes directly without using any processing
functions, as this will overwrite your input files when you run the mapping. You can
change the output file names using various functions e.g. the replace function as shown
below.
© 2011 Altova GmbH
Altova MapForce 2011
120
Dynamic input/output files per component
Dynamic file names - input / output
The output file names in the above case will be mf-expenses1.xml and mfexpenses2.xml.
The menu option File | Mapping Settings allows you to globally define the file path settings
used for the mapping project.
The "Ensure Windows path convention...." check box makes sure that Windows path
conventions are followed. When outputting XSLT2 (and XQuery), the currently processed file
name is internally retrieved using the document-uri function, which returns a path in the form
file:// URI for local files.
When this check box is active, a file:// URI path specification is automatically converted to a
complete Windows file path (e.g. "C:\...") to simplify further processing.
Altova MapForce 2011
© 2011 Altova GmbH
Dynamic input/output files per component
8.2
Dynamic file names as Input parameters
121
Dynamic file names as Input parameters
MapForce allows you to create special input components that can act as a parameter in the
command line execution of the compiled mapping. This specific type of input component cannot
be used inside a user-defined function, it is only available in the main mapping window.
To process a file using an Input parameter at runtime:
To define the path and file name at runtime, connect an input parameter component to the input
icon of the File node in the source component. Depending on the connections to other items,
this will define the input and/or the output file name.
The mf-ExpReport.xml entry in the Value field is only used for preview purposes in the Output
window. It has no effect on the parameter values used when running the code from the
command line. Please see Input parameters, overrides and command line parameters for more
information.
When you have generated and compiled your code you can supply the file name for the
mapping using the command line:
mapping.exe /InputFileName Filename.xml.
Where:
· /InputFileName is the name of the first parameter
·
Filename.xml is the second parameter i.e. the dynamic file name you want to be used
when running the application from the command line.
© 2011 Altova GmbH
Altova MapForce 2011
122
Dynamic input/output files per component
Multiple XML files from single XML source file
8.3
Multiple XML files from single XML source file
The content of the XML source file mf-ExpReport.xml, available in the ...\MapForceTutorial
folder, is shown below. It consists of the expense report for Fred Landis and contains five
expense items of different types. This example is available as Tut-ExpReport-dyn.mfd in the
...\Tutorial folder.
Aim:
To generate a separate XML file for each of the expense items listed below.
As the "type" element defines the specific expense item type, this is the item we will use to split
up the source file.
1. Insert a concat and constant function from the libraries pane.
2. Insert the auto-number function from the core | generator functions library of the
libraries pane.
3. Create the connections as shown above: type to value1, auto-number to value2 and the
Altova MapForce 2011
© 2011 Altova GmbH
Dynamic input/output files per component
Multiple XML files from single XML source file
123
constant to value3.
4. Connect the result parameter of the concat function to the File: item of the target
component. Note that File: <dynamic> is now displayed.
5. Define the remaining connections as needed.
6. Click the Output tab to see the result of the mapping.
Each record is now visible own Preview tab, the first one is shown above.
7. Click the drop-down list arrow arrow to see all the files that have been generated.
Clicking the Next/Previous
Output tab.
arrows allows you to see each of the files in the
Note:
· The type element supplies the first part of the file name e.g. Travel.
· The auto-number function supplies the file number increments (default settings are
start at=1 and increase=1) thus Travel1.
· The constant component supplies the file extension i.e. .xml, thus Travel1.xml is the
file name of the first file.
· Clicking the Save All icon
allows you to save the individual files directly from the
Output tab, without having to generate code.
© 2011 Altova GmbH
Altova MapForce 2011
124
Dynamic input/output files per component
8.4
Relative and absolute file paths
Relative and absolute file paths
A relative path is a path that does not start with a drive letter, i.e. it can be a file name without
path. The specific context in which the relative file name is used, defines the base path. The
handling of relative file names has changed in MapForce version 2010 due to the support for
mapping file names as data inside a mapping.
Previous versions of MapForce (prior to 2010) saved file paths relative to the *.MFD file for files
in the same, or a descendent folder, and changed them to absolute paths when they were
opened/loaded.
Since MapForce 2010, all references to external files, such as schemas or XML instance files,
are stored the way they are entered in the dialog box – in this way, relative paths can be used
where required.
Save all paths relative to MFD file
This new option, common to all component settings dialog boxes, saves all file paths (of the
component) relative to the location of the current MFD file. This allows you to move a mapping
together with all related files to a different location, while keeping all file references intact.
This means that:
· Absolute file paths will be changed to relative paths
· The parent directory "..\" will be also be inserted/written
· Using Save as... will adjust the file paths (relative to the MFD file) to the new location
you are saving the MFD file to
Please note:
Paths that reference a non-local drive, or use a URL, will not be made relative.
Altova MapForce 2011
© 2011 Altova GmbH
Dynamic input/output files per component
Relative and absolute file paths
125
There are two separate types of files that are referenced from an MFD file:
· Schema-type files (XML Schemas, WSDL, FlexText configuration files, …) entered in
the schema file field.
· Instance files entered in the Input xxx File, or Output xxx File fields.
Schema-type files
Schema-type files are used when designing a mapping. They define the structure of the
mapped input and output instance files. This information is used to display the item
trees/hierarchy in the various components. MapForce supports entering and storing a relative
path to schema-type files.
·
·
Relative paths to schema-type files will be always resolved relative to the MFD file.
Selecting a schema via the "Open" dialog, e.g. after inserting a new component, or
clicking the “Browse” button, always inserts the absolute path into the field.
© 2011 Altova GmbH
Altova MapForce 2011
126
Dynamic input/output files per component
·
·
Relative and absolute file paths
To set a relative path, which will also be stored in the MFD file, delete the path from the
text box, or type a relative path or file name. This will happen automatically on saving
the MFD file if the "Save all paths relative to MFD file" checkbox is activated. You may
also use "..\" to specify the parent folder of the MFD file.
Saving a MFD file that references files from the same directory, then moving the
complete directory to another location, does not update any absolute paths stored in
the mfd file. Users who use source control systems and different working directories
should therefore use relative paths, in this case.
Instance files and the execution environment
The processing of instance files is done in the generated XSLT, XQuery or in the generated
application, as well as MapForce preview.
In most cases it does not make sense to interpret relative paths to instance files as being
relative to the MFD file, because that path may not exist at execution time - the generated code
may be deployed to a different machine. Relative file names for instance files are therefore
resolved relative to the execution environment:
Target language
Base path for relative instance file name
XSLT/XSLT2
Path of the XSLT file
A new check box that ensures compatibility of generated code with mapping files (*.mfd) from
versions prior to Version 2010, has been added in the File | Mapping Settings dialog box, i.e. "
Make paths absolute in generated code".
The state of the check box is automatically set depending on what is opened, the check box is:
·
inactive if a new mapping file, i.e. version 2010, is created or opened
Relative paths for input and output instance files are written as is, into the generated
code.
This allows deployment of the generated code to a different directory or even machine.
You must ensure that files addressed using relative paths are available in the runtime
environment at the correct location.
·
active if an older mapping file from version 2009, 2008 etc. is opened
Relative paths for input and output instance files are made absolute (relative to the
*.MFD file) before generating code. This has the same effect as generating code with
an older version of MapForce.
Note that the source instance file name is also used for the following purposes:
· Detection of the XML root element and the referenced schema
· Validation against the selected schema
· Reading Excel worksheet names and columns
· To read column names and preview contents of text files (CSV or FLF)
New "schemaLocation" field for target XML files
Since schema references may be stored relative to the MFD file, and the generated XML file
from a target component is often in a different directory, there is a way to enter a separate
schemaLocation path for the target XML instance, so that the XML file can be validated there.
This is the field below the “Add schema/DTD reference” check box, of the Component Settings
dialog box (Double click a component to open it). A similar field exists for the taxonomy
reference in XBRL components.
Altova MapForce 2011
© 2011 Altova GmbH
Dynamic input/output files per component
Relative and absolute file paths
127
The path of the referenced/associated schema, entered in this field, is written into the
generated target instance files in the xsi:schemaLocation attribute, or into the DOCTYPE
declaration if a DTD is used.
Note: A URL e.g. http://mylocation.com/mf-expreport.xsd can also be entered here.
© 2011 Altova GmbH
Altova MapForce 2011
Chapter 9
Loops, groups and hierarchies
130
Loops, groups and hierarchies
9
Loops, groups and hierarchies
There are several ways of looping through source and target hierarchies which allow you to
define how you want to loop, or group, sets of data.
The following links show you how this can be achieved. Please note that these examples are
not sequential, they appear in various locations within the documentation.
Value-Map - lookup table
Priority Context
Altova MapForce 2011
© 2011 Altova GmbH
Loops, groups and hierarchies
131
Sequences, cardinality and priority context
MapForce generally maps data in an intuitive way, but there are some scenarios where the
resulting output seems to have too many, or too few items. This is what this section will cover.
General rule
Generally, every connection between a source and target item means: for each source item,
create one target item.
If the source node contains simple content (e.g. string, integer etc.) and the target node accepts
simple content, then the content is copied, and the data type is converted if necessary.
There are some exceptions to this rule, but it generally holds for all connections.
The Context and “current” items
MapForce displays the structure of a schema file as a hierarchy of mappable items in the
component. Each of these nodes may have many instances (or none) in the instance file or
database.
Example: If you look at the source component in PersonListByBranchOffice.mfd, there is only a
single node first (under Contact). In the BranchOffices.xml instance file, there are multiple
first nodes and Contact nodes having different content, under different Office parent nodes.
It depends on the current context (of the target node) which source nodes are actually selected
and have their data copied, via the connector, to the target component/item.
This context is defined by the current target node and the connections to its ancestors:
·
Initially the context contains only the source components, but no specific nodes. When
evaluating the mapping, MapForce processes the target root node first (PersonList),
then works down the hierarchy.
·
The connector to the target node is traced back to all source items directly or indirectly
connected to it, even via functions that might exist between the two components. The
© 2011 Altova GmbH
Altova MapForce 2011
132
Loops, groups and hierarchies
source items and functions results are added to the context for this node.
·
For each new target node a new context is established, that initially contains all items of
the parent node's context. Target sibling nodes are thus independent of each other, but
have access to all source data of their parent nodes.
Applied to the example mapping above (PersonListByBranchOffice.mfd):
·
The connection from Office through the filter (Office) to PersonList defines a single
office as the context for the whole target document (because PersonList is the root
element of the target component). The office name is supplied by the input component,
which has a default containing "Nanonull, Inc."
·
All connections/data to the descendants of the root element PersonList, are
automatically affected by the filter condition, because the selected single office is in the
context.
·
The connection from Contact to Person creates one target Person per Contact item of
the source XML (general rule). For each Person one specific Contact is added to the
context, from which the children of Person will be created.
·
The connector from first to First selects the first name of the current Contact and
writes it to the target item First.
Leaving out the connector from Contact to Person would create only one Person with
multiple First, Last, and Detail nodes, which is not what we want here. In such situations
, MapForce issues a warning and a suggestion to fix the problem: "You can try to
connect Contact with Person to resolve":
Altova MapForce 2011
© 2011 Altova GmbH
Loops, groups and hierarchies
133
Sequences
MapForce displays the structure of a schema file as a hierarchy of mappable items in the
component.
Depending on the (target) context, each mappable item of a source component can represent:
·
a single instance node of the assigned input file
·
a sequence of 0 to multiple instance nodes of the input file
If a sequence is connected to a target node, a loop is created to create as many target nodes
as there are source nodes.
If a filter is placed between the sequence and target node, the bool condition is checked for
each input node i.e. each item in the sequence. More exactly, a check is made to see if there is
at least one bool in each sequence that evaluates to true. The priority context setting can
influence the order of evaluation, see below.
As noted above, filter conditions automatically apply to all descendant nodes.
Note: If the source schema specifies that a specific node occurs exactly once, MapForce may
remove the loop and take the first item only, which it knows must exist. This optimization can be
disabled in the source Component Settings dialog box (check box "Enable input processing
optimizations based on min/maxOccurs").
Function inputs (of normal, non-sequence functions) work similar to target nodes: If a
sequence is connected to such an input, a loop is created around the function call, so it will
produce as many results as there are items in the sequence.
If a sequence is connected to more than one such function input, MapForce creates nested lo
ops which will process the Cartesian product of all inputs. Usually this is not desired, so only
one single sequence with multiple items should be connected to a function (and all other
parameters bound to singular current items from parents or other components).
Note: If an empty sequence is connected to such a function (e.g. concat), you will get an empty
sequence as result, which will produce no output nodes at all. If there is no result in your target
output because there is no input data, you can use the “substitute-missing” function to insert a
substitute value.
Functions with sequence inputs are the only functions that can produce a result if the input
sequence is empty:
·
·
·
"exists", "not-exists" and "substitute-missing" (also "is-not-null, "is-null" and
"substitute-null", which are aliases for the first three)
aggregate functions ("sum", "count" etc.)
regular user-defined functions that accept sequences (i.e. non-inlined functions)
The sequence input to such functions is always evaluated independently of the current target
node in the context of its ancestors. This also means that any filter components connected to
such functions, do not affect any other connections.
Priority context
Usually, function parameters are evaluated from top to bottom, but its is possible to define one
parameter to be evaluated before all others, using the priority context setting.
© 2011 Altova GmbH
Altova MapForce 2011
134
Loops, groups and hierarchies
In functions connected to the bool input of filter conditions, the priority context affects not only
the comparison function itself but also the evaluation of the filter, so it is possible to join together
two source sequences (see CompletePO.mfd, CustomerNo and Number).
In this example, the priority context forces ShortPO/CustomerNr to be evaluated before iterating
and filtering the Customer nodes from the Customers component. See example Priority Context
node/item.
Overriding the context
Some aggregate functions have an optional “parent-context” input.
If this input is not connected, it has no effect and the function is evaluated in the normal context
for sequence inputs (that is, in the context of the target node's parent).
Altova MapForce 2011
© 2011 Altova GmbH
Loops, groups and hierarchies
135
If the parent-context input is connected to a source node, the function is evaluated for each
“parent-context” node and will produce a separate result for each occurrence.
Exceptions to the general rule (for each source item, create one target item)
·
A target XML root element is always created once and only once. If a sequence is
connected to it, only the contents of the element will be repeated, but not the root
element itself. The result may, however, not be schema-valid. If attributes of the root
element are also connected, the XML serialization will fail at runtime, so you should
avoid connecting a sequence the root element. To create multiple output files, connect
the sequence to the "File" node instead, via some function that generates file names.
·
Some other nodes, like XML attributes, or the output component inside a user-defined
function, accept only a single value.
Bringing multiple nodes of the same source component into the context:
This is required in some special cases and can be done with Intermediate variables.
© 2011 Altova GmbH
Altova MapForce 2011
Chapter 10
Chained mappings / pass-through components
138
Chained mappings / pass-through components
10
Chained mappings / pass-through components
MapForce supports mappings that consist of multiple components in a mapping chain. Chained
mappings are mappings where two, or more, components are directly connected to another
target component. E.g. three components A, B, and C (shown below), where C is the target
component.
Intermediate component results, as well as the final mapping result, can be individually
previewed and generated as code.
Component B (ExpRep-Target) is in this case the "intermediate" component as it has both input
and output connectors.
Component B, as well as C, both have preview buttons
. This allows you to preview the
intermediate mapping result of B, as well as the final result of the chained mapping of
component C. Click the preview button of the respective component, then click Output to see
the mapping result.
Pass-through button
The intermediate component B, has an extra button in the component title bar called "passthrough". This button allows you to define that the set of input data is passed on to the following
component, e.g. component C.
Example Tut-ExpReport-chain.mfd.
Component A and B, filter out the Travel expense items from all the expense items.
Altova MapForce 2011
© 2011 Altova GmbH
Chained mappings / pass-through components
139
Components B and C work on the result set of A and B, and further filter out the expense items
where the Travel cost is less than 1500.
Please see Chained mappings - Input / Output for more on this example.
© 2011 Altova GmbH
Altova MapForce 2011
140
Chained mappings / pass-through components
Chained mappings - Pass-through active
10.1
Chained mappings - Pass-through active
The Tut-ExpReport-chain.mfd example is set up so that component A supplies all the
mapping data, using a sample XML file. The selected working XML file (mf-ExpReport.xml)
appears in the "Input XML File" field of the Component Settings dialog box. The Output XML
File name is automatically inserted when you define an Input XML file.
·
·
·
Intermediate component B does not have an Input/Output XML File assigned to it
File: (default).
Final component, C does not have an Output XML File assigned to it File: (default).
The preview button of component C is active.
If the pass-through button (on B) is active
, two separate sets of data are passed through to
the Output Preview window, via the intermediate component B.
I: The subset of mapping data from intermediate component B to target component C.
I.e. the Travel expenses below 1500.
Altova MapForce 2011
© 2011 Altova GmbH
Chained mappings / pass-through components
·
Chained mappings - Pass-through active
141
II: The result set of the mapping from component A to the intermediate component B. I.
e. all Travel expense items.
© 2011 Altova GmbH
Altova MapForce 2011
142
Chained mappings / pass-through components
Chained mappings - Pass-through active
Please note:
Each mapping result is displayed in its own Preview window. Click the scroll button(s) to
see the next/previous one.
Clicking the File combo box displays the result files(s) in a hierarchy. The final target
result is shown above, with the intermediate result files shown below. Click a file name
to select it, or use the keyboard keys to navigate through the file list and press Enter.
If pass-through is set as active, the files created by an intermediate component are
either automatically saved as temp files or written directly to disk, and used for further
processing of that components output. Please see Tools for more information.
The Preview XX of 1 means the number of final targets from the selected target
component, one in this case.
Altova MapForce 2011
© 2011 Altova GmbH
Chained mappings / pass-through components
Chained mappings - Pass-through active
143
The Preview ... (2) refers to the total number of results including all intermediate
components.
If an SPS file has been assigned to a target component, then clicking the HTML, RTF tab, will
show the resulting data in the respective StyleVision tab in MapForce.
© 2011 Altova GmbH
Altova MapForce 2011
144
Chained mappings / pass-through components
Chained mappings - Pass-through inactive
10.2
Chained mappings - Pass-through inactive
The Tut-ExpReport-chain.mfd example works differently if the pass-through button is inactive
on component "B".
1. Deactivate the pass-through button of component B, and check that the Preview button
of component C is active.
2. Click the Output button to see the result of the mapping.
An error message appears stating that the input file of the intermediate component
could not be accessed.
To make the input file of the intermediate component accessable, the result of the mapping of
component A to B must be saved, and the resulting file name be placed in the Input XML data
field of component B. Only then can data be displayed in the final component C.
1. Click the Preview button of component B to make it active, then click the Output button.
2. Click the
Save generated Output button in the Output Preview title bar and give the
XML file a name, e.g. mf-expReport-co.xml.
3. Copy the file name into the Input XML File field and click OK.
Please note:
Both the Input and Output file names must be identical (and present) for code
generation to occur.
4. Click the Preview button
button to see the result.
Altova MapForce 2011
of the final target component C, then click the Output
© 2011 Altova GmbH
Chained mappings / pass-through components
Chained mappings - Pass-through inactive
145
The mapping result from component B to C is displayed. I.e. the Travel expenses below
1500.
Please Note:
Activating the pass-through button, automatically disables the "Input XML File" field, of
the intermediate component, in the Component Settings dialog box. File: (default) is
then seen at the top of the component.
Data in the Preview tabs can be validated and saved.
If an SPS file has been assigned to a target component, then clicking the HTML, RTF tab, will
show the resulting data in the respective StyleVision tab in MapForce.
© 2011 Altova GmbH
Altova MapForce 2011
146
Chained mappings / pass-through components
Altova MapForce 2011
Chained mappings - Pass-through inactive
© 2011 Altova GmbH
Chapter 11
Intermediate variables
148
Intermediate variables
11
Intermediate variables
Intermediate variables are a special type of component used to solve various advanced
mapping problems. They store an intermediate mapping result for further processing.
·
Variables work in all languages except XSLT1.0.
·
Variable results are always sequences, i.e. a delimited list of values, and can also be
used to create sequences.
·
Variables are structural components, with a root node, and do not have instances (XML
files etc.) associated to them.
·
Variables make it possible to compare items of one sequence, to other items within the
same sequence.
·
Variables can be used to build intermediate sequences. Records can be filtered before
passing them on to a target, or filtered after the variable by using the position function
for example.
Difference between variables and chained mappings
Chained mappings
Variables
Involve two totally independent steps.
Evaluated depending on context /
scope. Controlled by "compute-when"
connection
Intermediate results are stored
Intermediate results are stored
externally in XML files when mapping is internally, not in any physical files,
executed.
when mapping is executed.
Intermediate result can be previewed
using preview button.
Variable result cannot be previewed.
To insert intermediate variables:
There are several ways of inserting intermediate variables: Using the menu option, by clicking
the Var. icon, or by right clicking input/output icons and creating variables based on the input/
output components.
1. Select Insert | Variable or click the Variable icon
in the icon bar. You can now
select if you want to insert a simple or complex variable.
Altova MapForce 2011
© 2011 Altova GmbH
Intermediate variables
149
2. Click the radio button for the type of variable you want to insert, i.e. Simple type, or
Complex type.
If you clicked the "Complex type" radio button:
3. Click the "Choose" button to select XML Schema for example, and select the Root item
from the next dialog box.
4. Click OK to insert the variable.
Complex variable:
Simple variable:
Have a single mappable item/value e.g. string, integer. Note that the "value" item can
be duplicated.
Alternate methods of inserting variables:
·
Right click an output icon of a component (e.g. BranchOffices) and select "Create
Variable from Source node".
© 2011 Altova GmbH
Altova MapForce 2011
150
Intermediate variables
This creates a complex variable using the same source schema and automatically
connects all items with a copy-all connection.
·
Right click an input icon of a target component (e.g. Contact) and select "Create
Variable for Target Node".
This creates a complex variable using the same schema as the target, with the Contact
item as the root node, and automatically connects all items with a copy-all connection.
·
Right click an output icon of a filter function (on-true/on-false) and select "Create
Variable from Source node".
Altova MapForce 2011
© 2011 Altova GmbH
Intermediate variables
151
This creates a complex component using the source schema, and automatically uses
the item linked to the filter input node/row, i.e. Contact, as the root element of the
intermediate component.
Compute-when
The compute-when input item allows you to control the scope of the variable; in other words
when and how often the variable value is computed when the mapping is executed. You do not
have to connect this input in many cases, but it can be essential to override the default context,
or to optimize mapping performance.
A subtree in the following text means the set of an item/node in a target component and all of
its descendants, e.g. a <Person> element with its <FirstName> and <LastName> child
elements.
Variable value means the data that is available at the output side of the variable component.
·
For simple variables, it is a sequence of atomic values that have the datatype specified
in the component properties.
·
For complex variables, it is a sequence of root nodes (of the type specified in the
component properties), each one including all its descendant nodes.
The sequence of atomic values (or nodes) may of course also contain only one, or even
zero elements. This depends on what is connected to the input side of the variable
component, and to any parent items in the source and target components.
Compute-when not connected (default)
If the compute-when input item is not connected (to an output node of a source component),
the variable value is computed whenever it is first used in a target subtree (via a connector
from the variable component directly to a node in the target component, or indirectly via
functions). The same variable value is also used for all target child nodes inside the subtree.
The actual variable value depends on any connections between parent items of the source and
target components (see "Loops, groups and hierarchies - The context").
This default behavior is the same as that of complex outputs of regular user-defined functions
and Web service function calls.
If the variable output is connected to multiple unrelated target nodes, the variable value is
computed separately for each of them. This can produce different results in each case, because
different parent connections influence the context in which the variable's value is evaluated.
Compute-when - connected
By connecting compute-when to an output node of a source component, the variable is
© 2011 Altova GmbH
Altova MapForce 2011
152
Intermediate variables
computed whenever that source item is first used in a target subtree.
The variable actually acts as if it were a child item of the item connected to compute-when.
This makes it possible to bind the variable to a specific source item, i.e. at runtime the variable
is re-evaluated whenever a new item is read from the sequence in the source component.
This relates to the general rule governing connections in MapForce - "for each source item,
create one target item". With compute-when, it means "for each source item, compute the
variable value".
Compute-once
Right clicking the "compute-when" icon and selecting "Compute Once" from the context menu,
changes the icon to "compute-when=once" and also removes the input icon.
This setting causes the variable value to be computed once before any of the target
components, making the variable essentially a global constant for the rest of the mapping.
In a user-defined function, the variable is evaluated each time the function is called, before the
actual function result is evaluated.
Parent-context
The main use of adding a parent-context, is when using multiple filters and you need an
additional parent node to iterate over.
To add a parent-context to a variable:
1. Right click the root node, e.g. PersonList and select "Add Parent Context" from the
context menu.
This adds a new node, "parent-context", to the existing hierarchy.
The parent context adds a virtual "parent" node to the hierarchy within the component.
This allows you to iterate over an additional node in the same, or different source
component.
Altova MapForce 2011
© 2011 Altova GmbH
Intermediate variables
11.1
Variables - use cases
153
Variables - use cases
Filtering out multiple instances of the same record from a source instance
Source data can often contain multiple instances of the same record. In most cases you would
only want one of these records to be mapped to the target component. The example below is
available as DistinctArticles.mfd in the ...\MapForceExamples folder.
The ArticlesWithDuplicates.xml file contains two articles both having the same article number
(two with article no. 1 and two with article no 3).
The article Number is used as the key in the group-by function, so it creates one group per
unique article number. Each group thus contains one article and all the unwanted duplicates of
that article. The next step is to extract the first item of each group and discard the rest.
The connection of the group output to "compute-when" causes the variable to be evaluated
once for each group, in the context of that group. This establishes an additional context level, as
if we had connected a parent element of the target Article element.
To select the first article of each group, we use the position function and a filter component,
which are connected to the variable input.
Applying filters to intermediate sequences:
Nodes in variable components can be duplicated as in any other type of component. This allows
you to build sequences from multiple different sources and then further process the sequence.
The screenshot below shows how PersonList.mfd could be modified using an intermediate
variable, and how constant components can also act as source items.
© 2011 Altova GmbH
Altova MapForce 2011
154
Intermediate variables
Variables - use cases
The Person node of the variable has been duplicated twice, and a filter has been added to filter
out those persons whose Last name starts with a letter higher than "G".
Numbering nodes of a filtered sequence
This example is available as PositionInFilteredSequence.mfd in ...\MapForceExamples folder
and uses the variable to collect the filtered contacts where the last name starts with a letter
higher than M.
The contacts are then passed on (from the variable) to the target component, with the position
function numbering these contacts sequentially.
The variable acts like another source component allowing the position function to process the
filtered sequence.
Altova MapForce 2011
© 2011 Altova GmbH
Intermediate variables
Variables - use cases
155
Extract specific data from a source components' anyType node
This example consists of a source component containing anyType elements from which we
want to filter specific data.
The intermediate variable is based on a schema that has nodes of the specific type of data that
we want to map, i.e. ArticleNr and Amount are both of type integer. That specific data is filtered
by ArticleNr. and passed on to the target component.
© 2011 Altova GmbH
Altova MapForce 2011
Chapter 12
How To... Filter, Transform, Aggregate
158
How To... Filter, Transform, Aggregate
12
How To... Filter, Transform, Aggregate
This section deals with common tasks that will be encountered when creating your own
mappings.
General:
I want to:
Read this section
Filter data based on specific criteria
Filter - retrieving dynamic data
Use dynamic/multiple input and output
files when mapping
Dynamic and multiple input/output files
per component
Map/use a derived complex type
(xsi:type)
Derived XML Schema types - mapping to
Create a recursive user-defined
mapping
Recursive user-defined mapping
Use min, max, sum, avg, and count
aggregate functions
Aggregate functions
Use an input component as a
parameter during command line
execution
Input values /overrides
Specify an alternative value for an input
component
Input values / overrides
Transform an input value to an output
value using a lookup table
Value-Map - Transforming input data
Run MapForce from the command line
Command line parameters
Know about type conversion when
mapping
Type conversion checking
Create my own catalog files
Catalog files in MapForce
Merge multiple source files into a single
target file
Merging multiple files into one target
Nodes
I want to:
Read this section
Test nodes; existing / not existing nodes
Node testing, exists / not exist
Group nodes by their content
Grouping nodes / node content
Map data based on the position of a
node in a sequence
Position of context items in a sequence
Comment a mapping / specific
connectors or nodes
Annotations / Commenting
Define the node which is to act as the
context node in a source file.
Priority context node/item
Altova MapForce 2011
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
© 2011 Altova GmbH
159
Altova MapForce 2011
160
How To... Filter, Transform, Aggregate
Filter - retrieving dynamic data, lookup table
12.1
Filter - retrieving dynamic data, lookup table
If you want to retrieve/filter data, based on specific criteria, please use the Filter component.
1. Click the filter icon
in the icon bar to insert the component.
This inserts the filter component in its "unconnected" form where "filter" is visible in the
title bar of the component.
As soon as a connection is made to the source component, the title bar name changes
to that of the item connected to the node/row item, in this case to Person.
Goal: to map all First/Last names from the Person table, where the Department primary key is
equal to 4.
·
·
·
·
The value of the PrimaryKey is compared to the value 4, supplied by the Constant
component, using the equal function.
PrimaryKey is mapped from the Department "root" table.
First and Last are mapped from the Person table, which is a child of the Department
"root" table.
Mappings defined under the same "root" table, in this case Department, maintain the
relationships between the their tables.
A filter has two input and output parameters: node/row and bool, and on-true, on-false. If the
Bool(ean) condition is true, then the content of the child items/nodes connected to the
node/row parameter, of the source component, are forwarded to the target component. If the
Boolean is false, then the complement values can be used by connecting to the on-false
parameter.
The first and last names of the persons in the IT Department with the primary key of 4, are
displayed in the Output tab.
Altova MapForce 2011
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
Filter - retrieving dynamic data, lookup table
161
For more examples on filtering data please see:
· Filtering XML data: Filtering data:
· Filtering CSV files by header and detail records:
·
·
·
Table relationships and filters:
Defining SQL-Where filters:
Database filters and queries:
·
Filter component tips: Filter components - Tips
© 2011 Altova GmbH
Altova MapForce 2011
162
How To... Filter, Transform, Aggregate
Filter - retrieving dynamic data, lookup table
12.1.1 Filter components - Tips
Avoid concatenating filter components
Every filter-component leads to a loop through the source data, thus accessing the source n
times. When you concatenate two filters, it loops n*n times.
Solution:
Use "logical-and" components to combine the boolean expressions of two filter-components.
The result is a single filter component looping only n-times.
Connect the "on-true/on-false" parameter of the filter component, to target parent items
Filter components work best when they are connected to parent items containing child items,
instead of individual items directly.
The filter boolean expression is therefore evaluated against the parent, before looping through
the child elements. Using filters mapped from a database table will generate:
·
·
"SELECT * FROM table WHERE <expression>" if the parent item is mapped, or
"SELECT * FROM table", and then evaluate for each row, if child items are mapped
Please note:
when connecting a filter from a source parent item, its also necessary to connect the
on-true/on-false parameter to the parent target element. If this cannot be done, then do
not apply this rule.
Connect the "on-false" parameter to map the complement node set
Connecting this parameter allows you quick access to the complement node set defined by the
current mapping. The same tips apply when using this parameter, connect to parent items etc.
Don't use filters to map to child data, if the parent item is mapped
Using a filter to map data from a source parent to a target parent, automatically applies the
same filter to every child item of the particular parent.
Filter components do not have to be used to supply filtered data to child items, if the parent item
can be mapped! You can therefore map child data directly.
Use priority-context to prioritize execution when mapping unrelated items
Mappings are always executed top-down; if you loop/search through two tables then each loop
is processed consecutively. When mapping unrelated elements, without setting the priority
context, MapForce does not know which loop needs to be executed first, it therefore
automatically selects the first table, or data source.
Solution:
Decide which table, or source data is to be looped/searched first, and then set the priority
context on the connector to that table. Please seePriority Context node/item for a more concrete
example.
To define a priority context:
· Right click an input icon and select "Priority Context" from the pop-up menu.
If the option is not available, mapping the remaining input icons of that component will
make it accessible.
Filters and source-driven / mixed content mapping
Source-driven mappings only work with direct connections between source and target
components. Connections that exist below a source-driven connection, are not taken as
source-driven and the items will be handled in target component item/node order.
Altova MapForce 2011
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
Filter - retrieving dynamic data, lookup table
163
A single filter where both outputs are connected to same/separate targets, acts as if there were
two separate filter components, one having a negated condition.
If an exception component is connected to one of the filter outputs, the exception condition is
checked when the mappings to the the other filter output are executed.
© 2011 Altova GmbH
Altova MapForce 2011
164
How To... Filter, Transform, Aggregate
12.2
Value-Map - transforming input data
Value-Map - transforming input data
The Value-Map component allows you to transform an input value to a different output value
using a lookup table. This is useful for converting different enumeration types. The component
only has one input and output item.
Note: if you want to retrieve/filter data based on specific criteria, please use the Filter
component see Filtering XML data: Filtering data.
To use a Value-Map component:
1. Select the menu option Insert | Value-Map, or click the Value-Map icon
bar.
in the icon
2. Double click the Value-Map component to open the value map table.
3. Click into the column headers and enter Weekday input in the first, and Day of the
Week in the second.
4. Enter the input value that you want to transform, in the Weekday input column.
5. Enter the output value you want to transform that value to, in the Day of the week
column.
6. Simply type in the (new entry) input field to enter a new value pair.
7. Click the datatype combo box, below the column header to select the input and output
Altova MapForce 2011
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
Value-Map - transforming input data
165
datatypes, e.g. integer and string.
Note: activate the Otherwise check box, and enter the value, to define an alternative
output value if the supplied values are not available on input. To pass through source
data without changing it please see Passing data through a Value-Map unchanged.
8. You can click the edit icons in the header rows to change the column names, which are
also displayed in the mapping. This will make it easier to identify the purpose of the
component in the mapping.
The Expense-valmap.mfd file in the ...\MapForceExamples\Tutorial\ folder is a sample
mapping that shows how the Value-Map can be used.
What this mapping does:
Extracts the day of the week from the Date item in the data source, converts the numerical
© 2011 Altova GmbH
Altova MapForce 2011
166
How To... Filter, Transform, Aggregate
Value-Map - transforming input data
value into text, and places it in the Weekday item of the target component i.e. Sunday, Monday
etc.
·
·
·
·
The weekday function extracts the weekday number from the Date item in the
ExpReport source file. The result of this function are integers ranging from 1 to 7.
The Value-Map component transforms the integers into weekdays, i.e. Sunday,
Monday, etc. as shown in the graphic at the top of this section.
If the output contains "Thursday", then the corresponding output "Prepare Financial
Reports" is mapped to the Weekday item in the target component.
Clicking the Output tab displays the target XML file with the transformed data.
Note:
Placing the mouse cursor over the value map component opens a popup containing the
currently defined values.
The output from various types of logical, or string functions, can only be a boolean "true
" or "false" value. The value you want to test for, must thus be entered into the input
field of the value map table e.g. "true".
Altova MapForce 2011
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
Value-Map - transforming input data
167
12.2.1 Passing data through a Value-Map unchanged
This section describes a mapping situation where some specific node data have to be
transformed, while the rest of the node data have to be passed on to the target node
unchanged.
An example of this would be a company that changes some of the titles in a subsidiary. In this
case it might change two title designations and want to keep the rest as they currently are.
The obvious mapping would be the one shown above, which uses the value-map component to
transform the specific titles.
Clicking the Output tab shows us the result of the mapping:
For those persons who are neither of the two types shown in the value-map component, the
Title element is deleted in the output file.
© 2011 Altova GmbH
Altova MapForce 2011
168
How To... Filter, Transform, Aggregate
Value-Map - transforming input data
Possible alternative:
Clicking the Otherwise check box and entering a substitute term, does make the Title node
reappear in the output file, but it now contains the same New Title for all other persons of the
company.
Solution:
Create a user-defined function containing the value-map component, and use the missing
node function to supply the original data for the empty nodes.
1. Click the value-map component and select Function | Create user-defined function
from Selection.
2. Enter a name for the function e.g. Pass-Through and click OK.
3. Insert a substitute-missing function from the core | node function section of the
Libraries pane, and create the connections as shown in the screen shot below.
Altova MapForce 2011
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
Value-Map - transforming input data
169
4. Click the Ouput tab to see the result:
Result of the mapping:
·
·
The two Title designations in the value-map component are transformed to New Title.
All other Title nodes of the source file, retain their original Title data in the target file.
Why is this happening:
The value-map component evaluates the input data.
·
If the incoming data matches one of the entries in the first column, the data is
transformed and passed on to the node parameter of substitute-missing, and then on to
Title2.
·
If the incoming data does not match any entry in the left column, then nothing is
passed on from value-map to the node parameter i.e. this is an empty node.
When this occurs the substitute-missing function retrieves the orignal node and data
from the Title node, and passes it on through the replace-with parameter, and then on
to Title2.
© 2011 Altova GmbH
Altova MapForce 2011
170
How To... Filter, Transform, Aggregate
Value-Map - transforming input data
12.2.2 Value-Map component properties
Actions:
Click the insert icon to insert a new row before the currently active one.
Click the delete icon to delete the currently active row.
Click the edit icon to edit the column header.
You can also reorder lines by dragging them.
Changing the column header:
Double clicking the column header, or clicking the pencil icon, allows you to edit the column
name and change it to something more meaningful. This will make it easier to identify the
purpose of the component, as the column names are also displayed in the mapping.
Using unique Input values:
The values entered into the input column must be unique. If you enter two identical values, both
are automatically highlighted for you to enable you to correct one of them.
Having corrected one of the values, the OK button is again enabled.
Altova MapForce 2011
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
12.3
Aggregate functions: min, max, sum, count, avg
171
Aggregate functions: min, max, sum, count, avg
Aggregate functions perform operations on a set of input values (or a sequence of values) as
opposed to a single value. The aggregate functions can all be found in the core library. The
mapping shown below is available as Aggregates.mfd in the ...\Tutorial folder.
Please also see Aggregate functions - summing nodes in XSLT1 and 2 on how to create
aggregate functions using Named Templates.
Java Selected
Aggregate functions have two input items.
· values is connected to the source item that provides the data, in this case Number.
· parent-context is connected to the item you want to iterate over, i.e. the context, in this
case over all Customers. The parameter is, howerver, optional.
The input instance in this case is an XML file containing the following data:
© 2011 Altova GmbH
Altova MapForce 2011
172
How To... Filter, Transform, Aggregate
·
·
Aggregate functions: min, max, sum, count, avg
The source data supplied to the values item is the number sequence 2,4,6,8.
The output component in this case is a simple text file.
Clicking the Output tab for the above mapping delivers the following result:
min=2, max=8, count=4, sum=20 and avg=5.
Altova MapForce 2011
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
12.4
Mappings and root element of target documents
173
Mappings and root element of target documents
Root element of target XML files
When creating a mapping to the root element of the target Schema/XML file, please make sure
that only one element is passed on to the target XML, as an XML document may only have one
root element.
Use the filter component to limit the mapped data to a single element or record.
Root element not limited:
If you do not limit the target schema root element, then all source elements/records are inserted
between the first root element. This will still create well-formed, but not valid, XML files.
© 2011 Altova GmbH
Altova MapForce 2011
174
How To... Filter, Transform, Aggregate
12.5
Boolean comparison of input nodes
Boolean comparison of input nodes
Data type handling in boolean functions (first introduced with MapForce 2006 SP2)
During the evaluation of the core functions, less-than, greater-than, equal, not-equal, less equal,
and greater equal, the evaluation result of two input nodes depends on the input values as well
as the data types used for the comparison.
Example:
The 'less than' comparison of the integer values 4 and 12, yields the boolean value "true", since
4 is less than 12. If the two input strings contain '4' and '12', the lexical analysis results in the
output value false", since '4' is alphabetically greater than the first character '1' of the second
operand (12).
If all "input" data types are of the same type, e.g. all input nodes are numerical types, or strings,
then the comparison is done for the common type.
Differing input node types
If the input nodes are of differing types, e. g. integer and string, or string and date, then the
following rule is applied:
The data type used for the comparison is always the most general, i. e. least restrictive,
input data type of the two input types.
Before comparing two values, all input values are converted to a common datatype. Using the
previous example; the datatype "string" is less restrictive than "integer". Comparing integer
value 4 with the string '12', converts integer value 4 to the string '4', which is then compared with
the string '12'.
The type handling for comparing mixed types follows the XSLT2 guidelines and prevents any
content-sensitive type conversion strategies. The advantage is that the logic is fixed by the
mapping and does not change dynamically.
Additional checks:
Version 2006SP2 additionally checks mappings for incompatible combinations and raises
validation errors and warnings if necessary. Examples are the comparison of dates with
booleans, or "datetimes" with numerical values.
In order to support explicit data type conversion, the following type conversion functions are
available in the core library: "boolean", "number" and "string". In the previously mentioned
context, these three functions are suitable to govern the interpretation of comparisons.
Adding these conversion functions to input nodes of related functions might change the
common data type and the result of the evaluation in the desired manner. E. g. if string nodes
store only numeric values, a numerical comparison is achieved by adding the "number"
conversion function (in the conversion section of the core library) to each input node.
Altova MapForce 2011
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
12.6
Priority Context node/item
175
Priority Context node/item
When applying a function to different items in a schema, MapForce needs to know what the
context node will be. All other items are then processed relative to this one. This is achieved by
designating the item (or node) as the priority context.
The CompletePO.mfd file available in the ...\MapForceExamples folder, is shown below.
Please note that there are multiple source components in this example. ShortPO, Customers,
and Articles are all schemas with associated XML instance files. The data from each, are then
mapped to the CompletePO schema / XML file. The priority context icon, is enclosed in a circle
as a visual indication.
·
·
·
·
·
·
The CustomerNr in ShortPO is compared with the item Number in the Customers file.
CustomerNr has been designated as the priority context, and is placed in the a
parameter of the equal function.
The Customers file is then searched (once) for the same number. The b parameter
contains the Number item from the Customers file.
If the number is found, then the result is passed to the bool parameter of the filter
function.
The node/row parameter passes on the Customers data to "on-true" when the bool
parameter is true, i.e. when the same number has been found.
The rest of the customer data is then passed on as: Number, FirstName, LastName
items, are all connected to the corresponding items in the target schema.
Designating the b parameter of the equal function (i.e. item Number), as the priority context
would cause:
· MapForce to load the first Number into the b parameter
· Check against the CustomerNr in a, if not equal,
· Load the next Number into b, check against a, and
· Iterate through every Number in the file while trying to find that number in ShortPO.
© 2011 Altova GmbH
Altova MapForce 2011
176
How To... Filter, Transform, Aggregate
12.7
Merging multiple files into one target
Merging multiple files into one target
MapForce allows you to merge multiple files into a single target file.
This example merges multiple source components, with different schemas to a target schema.
To merge an arbitrary number of files using the same schema, see "Dynamic file names - input
/ output".
The CompletePO.mfd file available in the ...\MapForceExamples folder, shows how three
XML files are merged into one purchasing order XML file.
Note that multiple source component data are combined into one target XML file - CompletePO
·
ShortPO is a schema with an associated XML instance file and contains only customer
number and article data, i.e. Line item, number and amount.
·
Customers is a schema with an associated XML instance file and contains customer
number and customer information details, i.e. Name and Address info. (There is only
one customer in this file with the Customer number of 3)
·
Articles is a schema with an associated XML instance and contains article data, i.e.
article name number and price.
·
CompletePO is a schema file without an instance file as all the data is supplied by the
three XML instance files. The hierarchical structure of this file makes it possible to
merge and output all XML data.
This schema file has to be created in an XML editor such as XMLSpy, it is not
Altova MapForce 2011
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
Merging multiple files into one target
177
generated by MapForce (although it would be possible to create if you had an
CompletePO.xml instance file).
The stucture of CompletePO is a combination of the source XML file structures.
The filter component (Customer) is used to find/filter out the data where the customer numbers
are identical in both the ShortPO and Customers XML files, and pass on the associated data to
the target CompletePO component.
·
The CustomerNr in ShortPO is compared with the Number in Customers using the
"equal" function.
·
As ShortPO only contains one customer (number 3), only customer and article data for
customer number 3, can be passed on to the filter component.
·
The node/row parameter, of the filter component, passes on the Customer data to
"on-true" when the bool parameter is true, i.e. when the same number has been found,
in this case customer number 3.
·
The rest of the customer and article data are passed on to the target schema through
the two other filter components.
© 2011 Altova GmbH
Altova MapForce 2011
178
How To... Filter, Transform, Aggregate
12.8
Command line parameters
Command line parameters
The command line parameter syntax for MapForce is shown below.
General syntax:
MapForce.exe filename [ /target outputdir [ /GLOBALRESOURCEFILE globalresourcefilename
] [ /GLOBALRESOURCECONFIG configurationname ] [ /LOG logfilename ] ]
target
·
·
·
{ XSLT | XSLT2 }
The square brackets [...] denote optional parameters.
The curly brackets {...} denote a parameter group containing several choices.
The pipe symbol | denotes OR, e.g. /XSLT or /XSLT2
MapForce.exe returns an exit code of 0, if the command line execution was successful.
Any other value indicates a failure. You can check for this code using the IF
ERRORLEVEL command in batch files.
Description of general parameters:
filename
outputdir
/LOG logfilename
path of YourMAPFORCEfile.MFD
If the path, or file name contains a space, please use quotes
around the path/file name i.e. "c:\Program Files\...\Filename"
For code generation, the directory the generated mapping code
is to be placed in. outputdir is now optional if you use the /target
parameter. If an output path is not supplied, the working/current
directory will be used.
Relative means only the file name is supplied, not a complete
path starting with a drive letter.
generates a log file called logfilename. Logfilename can be a full
path name, i.e. directory and file name of the log file, but the
directory must exist for the logfile to be generated if a full path is
supplied.
If you only specify the file name, then the file will be placed in the
/outputdir directory.
Description of target parameters:
/XSLT
/XSLT2
generates XSLT1 code
generates XSLT2 code
Description of global resource parameters:
/GLOBALRESOURCEFILE globalresourcefilename uses the global resources defined in the
specified global resource file
/GLOBALRESOURCECONFIG configurationname uses the specified global resource
configuration
Examples:
MapForce.exe filename starts MapForce and opens the file defined by filename.
I) generate all XSLT files and output a log file.
MapForce.exe filename /XSLT outputdir /LOG logfilename
Altova MapForce 2011
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
Command line parameters
179
II) generate all XSLT files and use all global resources of the global resource file for the
specified configuration
Mapforce.exe filename /XSLT outputdir /GLOBALRESOURCEFILE
globalresourcefilename /GLOBALRESOURCECONFIG configurationname
Having executed the command line, several files are produced:
·
·
·
The generated XSLT file
A batch file called DoTransform.bat which uses AltovaXML to transform the XML file.
A log file, if one was specified in the command line.
To transform the XML file using the generated XSLT:
1. Download and install the free AltovaXML engine from the AltovaXML download page.
AltovaXML is installed to c:\Program Files\Altova\AltovaXML2011\ per default.
2. Start the DoTransform.bat batch file located in the previously designated output
folder.
This generates the output file in the current folder.
Note:
You might need to add the AltovaXML insallation location to the path variable of the
Environment Variables.
© 2011 Altova GmbH
Altova MapForce 2011
180
How To... Filter, Transform, Aggregate
Command line - defining input/output files
12.9
Command line - defining input/output files
MapForce allows you to create special "input" components that can act as parameters in the
command line execution of a mapping. These input components allow you to define the content
of the parameter when executing the command line, as well as the values when previewing the
output in MapForce. The content of a parameter can be a file name, or a specific value.
This specific type of "input" component cannot be used inside a user-defined function, it is only
available in the main mapping window.
The mapping below (FileNamesAsParameters.mfd in ...\MapForceExamples) uses two such
components, one to supply the input file name and the other, the output file name, to the File:
<dynamic> item of each component. See Dynamic input/output files per component for more
information on dynamic file names.
To define an input component / command line parameter:
1. Use the menu option Function | Insert Input to insert the component.
This opens the Create Input dialog box.
2. Enter a name for the function e.g. InputFileName and select the datatype you want to
use, e.g. string.
Altova MapForce 2011
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
Command line - defining input/output files
181
3. Click OK to complete the definition.
4. Use the same method to create the OutputFileName component/parameter.
The /InputFileName and /OutputFileName components are the special input
components in the mapping that allow you to use them as file name parameters in the
command line execution.
The other fields in this dialog box are used to specify the preview output (or files) while
running MapForce. They are not needed when executing from the command line. The
two constant components (shown in the mapping above) supply default file names to
the input components for the preview output. See Input parameters - default and
preview settings.
© 2011 Altova GmbH
Altova MapForce 2011
182
How To... Filter, Transform, Aggregate
Input parameters - default and preview settings
12.10 Input parameters - default and preview settings
The mapping below (available as FileNamesAsParameters.mfd in ...\MapForceExamples
folder) uses two input components, one to supply the input file name and the other, the output
file name, to the File: <dynamic> item of each component.
The /InputFileName and /OutputFileName components are the special input components in
the mapping, that allow you to use them as file name parameters in the command line
execution. If you want to define the input data from the command line, please see Command
line - defining input/output files.
To define an input component:
1. Use the menu option Function | Insert Input to insert the component.
This opens the Create Input dialog box.
2. Enter a name for the function e.g. InputFileName and select the datatype you want to
use, e.g. string.
Altova MapForce 2011
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
Input parameters - default and preview settings
183
3. Click the "Specify value" check box, and enter a value/string in the textbox, that you
want to use when previewing the output, e.g. altova-cmpy.xml.
4. Click the OK button then the Output button to see the result.
The altova-cmpy.xml is used as the source file for the mapping and the mapped data
appears in the output window.
The value entered in the Design-time Execution value field is only applicable when
previewing results in the Output tab. It is not used for code generation, or command
line execution of mappings.
To define a default value for the output preview:
Having defined the input component and clicked the OK button, the component appears in the
mapping area as shown below. Note that a default item appears on the left, while the
component name is the name of the other mappable item.
1. You can use a Constant component to supply the default value as shown in the
example above, e.g. Altova_Hierarchical.xml.
2. Create the constant component and connect it to the default item of the input
component.
To use the default value of an Input component:
1. Double click the input component and deselect the "Input is required" and "Specify
value" check boxes.
© 2011 Altova GmbH
Altova MapForce 2011
184
How To... Filter, Transform, Aggregate
Input parameters - default and preview settings
2. Click the Output tab to see the result of the mapping. The data from the
Altova_Hierarchical.xml file is now used for the preview.
Generating XSLT 1.0 or XSLT 2.0 code:
The value in the "Value" text box is written into the DoTransform.bat batch file. This batch file
is automatically generated for execution in the AltovaXML engine. If you want to use a different
input (or output) file you can change the name in the batch file.
If no value has been entered in the "Value" text box, then the default value, present in the
generated XSLT code, will be used.
Using default parameters/values in command line execution: ?? true ??
The "Input is required" check box must be set to inactive (before compiling the code) to use the
default parameter from the command line. Enter mapping.exe to have the generated code use
the default parameter from the command line.
Altova MapForce 2011
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
Node testing, position and grouping
185
12.11 Node testing, position and grouping
The node testing functions allow you to test for the existence of nodes in the XML instance
files. Elements or attributes defined as optional in the XML Schema, may, or may not, appear in
the XML instance file. Use these functions to perform the specific node test and base further
processing on the result.
Exists
Returns true if the node exists, else returns false.
The "HasMarketingExpenses.mfd" file in the ...\MapForceExamples folder contains the small
example shown below.
If an expense-item exists in the source XML, then the "hasExpenses" attribute is set to "true" in
the target XML/Schema file.
Not-exists
Returns false if the node exists, else returns true. Please see Mapping missing nodes - using
Not-exists for an example on how to map missing nodes.
substitute-missing
This function is a convenient combination of exists and a suitable if-else condition. Used to
map the current field content if the node exists in the XML source file, otherwise use the item
mapped to the "replace-with" parameter.
© 2011 Altova GmbH
Altova MapForce 2011
186
How To... Filter, Transform, Aggregate
Node testing, position and grouping
In the image above, the existence of the node "Phone" is checked in the XML instance file. If
the node is not present, then the value supplied by the constant is mapped.
Altova MapForce 2011
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
Node testing, position and grouping
187
12.11.1 Mapping missing nodes - using Not-exists
The example below shows how you can use the not-exists function to map nodes that do not
exist in one of a pair of source files.
What this mapping does is to:
·
·
·
Compare the nodes of two source XML files
Filter out the nodes, of the first source XML file, that do not exist in the second source
XML file
Map only the missing nodes, and their content, to the target file.
© 2011 Altova GmbH
Altova MapForce 2011
188
How To... Filter, Transform, Aggregate
Node testing, position and grouping
The two XML instance files are shown below, the differences between them are:
· a.xml at left, contains the node <b kind="3">, which is missing from b.xml.
· b.xml at right, contains the node <b kind="4"> which is missing from a.xml.
a.xml
·
·
·
b.xml
The equal function compares the kind attribute of both XML files and passes the result
to the filter.
A not-exists function is placed after the initial filter, to select the missing nodes of each
of the source files.
The second filter is used to pass on the missing node and other data only from the a.
xml file to the target.
The mapping result is that the node missing from b.xml, <b kind="3">, is passed on to
the target component.
Altova MapForce 2011
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
Node testing, position and grouping
189
12.11.2 Position of context items in a sequence
The position function allows you to determine the position of a specific node in a sequence, or
use a specific position to filter out items based on that position.
The context item is defined by the item connected to the "node" parameter of the position
function, Person, in the example below.
The simple mapping below adds a position number to each Person of each Department.
The position number is reset for each Department in the Office.
Using the position function to filter out specific nodes
Using the position function in conjunction with a filter allows you to map only those specific
nodes that have a certain position in the source component.
The filter "node/row" parameter and the position "node" must be connected to the same item of
the source component, to filter out a specific position of that sequence.
© 2011 Altova GmbH
Altova MapForce 2011
190
How To... Filter, Transform, Aggregate
Node testing, position and grouping
What this mapping does is to output:
· The second Person in each Department
· of each Office in Altova.
Altova MapForce 2011
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
Node testing, position and grouping
191
12.11.3 Grouping nodes / node content
MapForce now supports the grouping of nodes and their content. These functions can be found
in the "Sequence functions" section in the Libraries window.
distinct-values
Allows you to remove duplicate values from a result set and map the unique items to the target
component.
In the example below, the content of the source component "Title" items, are scanned and each
unique title is mapped to the Department / Name item in the target component.
Note that the sequence of the individual Title items in the source component are retained when
mapped to the target component.
group-adjacent
Groups the input sequence into a series of groups where each set of identically adjacent items/
© 2011 Altova GmbH
Altova MapForce 2011
192
How To... Filter, Transform, Aggregate
Node testing, position and grouping
nodes are placed into a new separate group.
Given the CSV file shown below, what we want to happen is to have all the Header and Detail
records in their own groups.
·
·
·
·
·
A new group is started with the first element, in this case H.
As the next element (or key) in the sequence is different, i.e. D, this starts a second
group called D.
The next two D elements are now added to the same group D, as they are of the same
type.
A new H group is started with a single H element.
Followed by a new D group containing two D elements.
Altova MapForce 2011
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
Node testing, position and grouping
193
Note that group-adjacent uses the content of the node/item as the grouping key! The
content of the Head_Detail field is used to group the records by record type in the
target.
group-by
Groups the input sequence by distinct keys and outputs the series of groups along with their
keys. The example below shows how this works:
·
·
The key that defines the specific groups of the source component is the Title item. This
is used to group the persons of the company.
The group name is placed in the Department/Name item of the target component, while
the concatenated person first and last names are placed in the Person/First child item.
© 2011 Altova GmbH
Altova MapForce 2011
194
How To... Filter, Transform, Aggregate
Node testing, position and grouping
Note that group-by uses the content of the node/item as the grouping key! The content of the
Title field is used to group the persons and is mapped to the Department/Name item in the
target.
Note also: there is an implied filter of the rows from the source document to the target
document, which can be seen in the included example. In the target document, each
Department item only has those Person items that match the grouping key, as the group-by
component creates the necessary hierarchy on the fly.
If you have a flat hierarchy (CSV, FLF, etc) with a dynamic output file name, built in part from
the key value, the implied filter still exists. This means that you may not need to connect the
'groups' output to any item in the target component.
Clicking the Ouput button shows the result of the grouping process.
Altova MapForce 2011
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
Node testing, position and grouping
195
group-starting-with
This function groups the input sequence by the supplied item, if it exists in the source data. A
boolean function is needed to test the input data.
The function creates groups based on the first item of a group, in this example HDR.
The value of the item/nodes do not need to be identical or even exist. The node "pattern" i.e.
the node/item names need to be identical for the grouping to occur.
The result above shows that a new group was started for every HDR element.
© 2011 Altova GmbH
Altova MapForce 2011
196
How To... Filter, Transform, Aggregate
Node testing, position and grouping
group-ending-with
This complements the group-starting-with function, and ends each group of the input sequence
by the supplied item, if it exists in the source data. A boolean function is needed to test the input
data.
Using the same source component as the group-starting-with example above, this example
shows the result when using DTL as the group-ending-with item.
In this case the value of the item/nodes do not need to be identical or even exist. The node "
pattern" i.e. the node/item names need to be identical for the grouping to occur.
The result above shows that a new group was started wherever DTL can be the last element.
set-empty
Allows you to cancel of an XBRL document that were defined higher up the XBRL component/
taxonomy.
Altova MapForce 2011
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
Using DTDs as "schema" components
197
12.12 Using DTDs as "schema" components
MapForce 2006 SP2 and above, support namespace-aware DTDs for source and target
components. The namespace-URIs are extracted from the DTD "xmlns"-attribute declarations,
to make mappings possible.
Adding DTD namespace URIs
There are however some DTDs, e.g. DTDs used by StyleVision, which contain xmlns*-attribute
declarations, without namespace-URIs. These DTDs have to be extended to make them
useable in MapForce.
·
The DTD has to be altered by defining the xmlns-attribute with the namespace-URI as
shown below:
<!ATTLIST fo:root
xmlns:fo CDATA #FIXED 'http://www.w3.org/1999/XSL/Format'
...
>
© 2011 Altova GmbH
Altova MapForce 2011
198
How To... Filter, Transform, Aggregate
Type conversion checking
12.13 Type conversion checking
From MapForce 2006 SP2 on, the generated applications and preview (with the Built-in
execution engine) check for type-conversion errors in more detail, inline with XSLT2 and
XQUERY.
Converting values from one type to another may now result in a runtime-error, where in prior
versions of MapForce would have produced some type of result.
Example: conversion of a xs:string 'Hello', to xs:decimal
MapForce 2006 Versions up to, and including SP1:
XSLT:
XSLT2:
Xquery:
Preview with
Built-in execution
engine:
C++ app:
C# app:
Java app:
'Hello' (or 'NaN' when passed to a function dealing with
number)
error: "invalid lexical value"
error: "invalid lexical value"
0
0
error: "values not convertable"
error: "values not convertable"
MapForce 2006 SP2:
XSLT:
XSLT2:
Xquery:
Preview with
Built-in execution
engine:
C++ app:
C# app:
Java app:
'Hello' (or 'NaN' when passed to a function dealing with
number)
error: "invalid lexical value"
error: "invalid lexical value"
error: "string-value 'Hello' could not be converted to
decimal"
error: "values not convertable"
error: "values not convertable"
error: "values not convertable"
If type-conversion-errors occur, check that the types have been handled correctly. E.g. use the
lang:numeric() function, to check if the source-value may be converted into a number, and then
an if-else component to pass a different value in case it fails (e.g. a constant containing -1, on
the value-false parameter).
Altova MapForce 2011
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
Catalog files in MapForce
199
12.14 Catalog files in MapForce
MapForce supports a subset of the OASIS XML catalogs mechanism. The catalog mechanism
enables MapForce to retrieve commonly used schemas (as well as stylesheets and other files)
from local user folders. This increases the overall processing speed, enables users to work
offline (that is, not connected to a network), and improves the portability of documents (because
URIs would then need to be changed only in the catalog files.)
The catalog mechanism in MapForce works as outlined below.
RootCatalog.xml
When MapForce starts, it loads a file called RootCatalog.xml (structure shown in listing below
), which contains a list of catalog files that will be looked up. You can modify this file and enter
as many catalog files to look up as you like, each in a nextCatalog element. Each of these
catalog files is looked up and the URIs in them are resolved according to the mappings
specified in them.
<?xml version="1.0" encoding="UTF-8"?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"
xmlns:spy="http://www.altova.com/catalog_ext"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:oasis:names:tc:entity:xmlns:xml:catalog
Catalog.xsd">
<nextCatalog catalog="%PersonalFolder%/Altova/%AppAndVersionName%/
CustomCatalog.xml"/>
<nextCatalog catalog="CoreCatalog.xml"/>
<!-- Include all catalogs under common schemas folder on the first directory
level -->
<nextCatalog spy:recurseFrom="%AltovaCommonFolder%/Schemas" catalog="
catalog.xml" spy:depth="1"/>
<!-- Include all catalogs under common XBRL folder on the first directory
level -->
<nextCatalog spy:recurseFrom="%AltovaCommonFolder%/XBRL" catalog="
catalog.xml" spy:depth="1"/>
</catalog>
In the listing above, notice that in the Schemas and XBRL folders of the folder identified by the
variable %AltovaCommonFolder% are catalog files named catalog.xml. (The value of the
%AltovaCommonFolder% variable is given in the table below.)
The catalog files in the Altova Common Folder map the pre-defined public and system
identifiers of commonly used schemas (such as SVG and WSDL) and XBRL taxonomies to
URIs that point to locally saved copies of the respective schemas. These schemas are installed
in the Altova Common Folder when MapForce is installed.You should take care not to duplicate
mappings in these files, as this could lead to errors.
CoreCatalog.xml, CustomCatalog.xml, and Catalog.xml
In the RootCatalog.xml listing above, notice that CoreCatalog.xml and CustomCatalog.xml
are listed for lookup:
·
·
·
CoreCatalog.xml contains certain Altova-specific mappings for locating schemas in
the Altova Common Folder.
CustomCatalog.xml is a skeleton file in which you can create your own mappings. You
can add mappings to CustomCatalog.xml for any schema you require but that is not
addressed by the catalog files in the Altova Common Folder. Do this using the
supported elements of the OASIS catalog mechanism (see below).
There are a number of Catalog.xml files in the Altova Common Folder. Each is inside
the folder of a specific schema or XBRL taxonomy in the Altova Common Folder, and
© 2011 Altova GmbH
Altova MapForce 2011
200
How To... Filter, Transform, Aggregate
Catalog files in MapForce
each maps public and/or system identifiers to URIs that point to locally saved copies of
the respective schemas.
Location of catalog files and schemas
The files RootCatalog.xml and CoreCatalog.xml are installed in the MapForce application
folder. The file CustomCatalog.xml is located in your MyDocuments/Altova/MapForce folder.
The catalog.xml files are each in a specific schema folder, these schema folders being inside
the folders: %AltovaCommonFolder%\Schemas and %AltovaCommonFolder%\XBRL.
Shell environment variables and Altova variables
Shell environment variables can be used in the nextCatalog element to specify the path to
various system locations (see RootCatalog.xml listing above). The following shell environment
variables are supported:
%AltovaCommonFold
er%
C:\Program Files\Altova\CommonMapForce
%DesktopFolder%
Full path to the Desktop folder for the current user.
%ProgramMenuFolde
r%
Full path to the Program Menu folder for the current user.
%StartMenuFolder%
Full path to Start Menu folder for the current user.
%StartUpFolder%
Full path to Start Up folder for the current user.
%TemplateFolder%
Full path to the Template folder for the current user.
%AdminToolsFolder
%
Full path to the file system directory that stores administrative tools for
the current user.
%AppDataFolder%
Full path to the Application Data folder for the current user.
%CommonAppDataFol
der%
Full path to the file directory containing application data for all users.
%FavoritesFolder%
Full path of the Favorites folder for the current user.
%PersonalFolder%
Full path to the Personal folder for the current user.
%SendToFolder%
Full path to the SendTo folder for the current user.
%FontsFolder%
Full path to the System Fonts folder.
%ProgramFilesFold
er%
Full path to the Program Files folder for the current user.
%CommonFilesFolde
r%
Full path to the Common Files folder for the current user.
%WindowsFolder%
Full path to the Windows folder for the current user.
%SystemFolder%
Full path to the System folder for the current user.
%CommonAppDataFol
der%
Full path to the file directory containing application data for all users.
%LocalAppDataFold
er%
Full path to the file system directory that serves as the data repository
for local (nonroaming) applications.
Altova MapForce 2011
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
%MyPicturesFolder
%
Catalog files in MapForce
201
Full path to the MyPictures folder.
How catalogs work
Catalogs are commonly used to redirect a call to a DTD to a local URI. This is achieved by
mapping, in the catalog file, public or system identifiers to the required local URI. So when the
DOCTYPE declaration in an XML file is read, the public or system identifier locates the required
local resource via the catalog file mapping.
For popular schemas, the PUBLIC identifier is usually pre-defined, thus requiring only that the
URI in the catalog file point to the correct local copy. When the XML document is parsed, the
PUBLIC identifier in it is read. If this identifier is found in a catalog file, the corresponding URL in
the catalog file will be looked up and the schema will be read from this location. So, for
example, if the following SVG file is opened in MapForce:
<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg width="20" height="20" xml:space="preserve">
<g style="fill:red; stroke:#000000">
<rect x="0" y="0" width="15" height="15"/>
<rect x="5" y="5" width="15" height="15"/>
</g>
</svg>
This document is read and the catalog is searched for the PUBLIC identifier. Let's say the
catalog file contains the following entry:
<catalog>
...
<public publicId="-//W3C//DTD SVG 1.1//EN" uri="schemas/svg/svg11.dtd"/>
...
</catalog>
In this case, there is a match for the PUBLIC identifier, so the lookup for the SVG DTD is
redirected to the URI schemas/svg/svg11.dtd (this path is relative to the catalog file), and this
local file will be used as the DTD. If there is no mapping for the Public ID in the catalog, then
the URL in the XML document will be used (in the example above:
http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd).
The catalog subset supported by MapForce
When creating entries in CustomCatalog.xml (or any other catalog file that is to be read by
MapForce), use only the following elements of the OASIS catalog specification. Each of the
elements below is listed with an explanation of their attribute values. For a more detailed
explanation, see the XML Catalogs specification. Note that each element can take the
xml:base attribute, which is used to specify the base URI of that element.
·
·
·
·
·
<public publicId="PublicID of Resource" uri="URL of local file"/>
<system systemId="SystemID of Resource" uri="URL of local file"/>
<uri name="filename" uri="URL of file identified by filename"/>
<rewriteURI uriStartString="StartString of URI to rewrite"
rewritePrefix="String to replace StartString"/>
<rewriteSystem systemIdStartString="StartString of SystemID"
rewritePrefix="Replacement string to locate resource locally"/>
© 2011 Altova GmbH
Altova MapForce 2011
202
How To... Filter, Transform, Aggregate
Catalog files in MapForce
In cases where there is no public identifier, as with most stylesheets, the system identifier can
be directly mapped to a URL via the system element. Also, a URI can be mapped to another
URI using the uri element. The rewriteURI and rewritsSystem elements enable the rewriting
of the starting part of a URI or system identifier, respectively. This allows the start of a filepath to
be replaced and consequently enables the targeting of another directory. For more information
on these elements, see the XML Catalogs specification.
File extensions and intelligent editing according to a schema
Via catalog files you can also specify that documents with a particular file extension should have
MapForce's intelligent editing features applied in conformance with the rules in a schema you
specify. For example, if you create a custom file extension .myhtml for (HTML) files that are to
be valid according to the HTML DTD, then you can enable intelligent editing for files with these
extensions by adding the following element of text to CustomCatalog.xml as a child of the
<catalog> element.
<spy:fileExtHelper ext="myhtml" uri="schemas/xhtml/xhtml1-transitional.dtd"/>
This would enable intelligent editing (auto-completion, entry helpers, etc) of .myhtml files in
MapForce according to the XHTML 1.0 Transitional DTD. Refer to the catalog.xml file in the
%AltovaCommonFolder%\Schemas\xhtml folder, which contains similar entries.
XML Schema and catalogs
XML Schema information is built into MapForce and the validity of XML Schema documents is
checked against this internal information. In an XML Schema document, therefore, no
references should be made to any schema for XML Schema.
The catalog.xml file in the %AltovaCommonFolder%\Schemas\schema folder contains
references to DTDs that implement older XML Schema specifications. You should not validate
your XML Schema documents against either of these schemas. The referenced files are
included solely to provide MapForce with entry helper info for editing purposes should you wish
to create documents according to these older recommendations.
More information
For more information on catalogs, see the XML Catalogs specification.
Altova MapForce 2011
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
Derived XML Schema types - mapping to
203
12.15 Derived XML Schema types - mapping to
MapForce supports the mapping to/from derived types of a complex type. Derived types are
complex types of an XML Schema that use the xsi:type attribute to identify the specific derived
types.
The screenshot below shows the definition of the derived type "US-Address", in XMLSpy. The
base type (or originating complex type) is, in this case, AddressType. Two extra elements were
added to create the derived type US-Address.
Mapping to derived types in MapForce:
1. Insert the XML schema MFCompany.xsd that is available in the ...\Tutorial folder, click
Skip, then select Company as the root element.
2. Click the TYPE button to the right of the Address element which shows that derived
types exist in the Schema component.
3. Click the check box next to the derived type you want to use, e.g. US-Address, and
confirm with OK.
© 2011 Altova GmbH
Altova MapForce 2011
204
How To... Filter, Transform, Aggregate
Derived XML Schema types - mapping to
A new element Address xsi:type="US-Address" has been added to the component.
4. Click the expand button to see the mappable items of the element.
5. You can now map directly to/from these items.
Please note:
You can include/insert multiple derived types by selecting them in the Derived Types
dialog box, each will have its own xsi:type element in the component.
Altova MapForce 2011
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
Recursive user-defined mapping
205
12.16 Recursive user-defined mapping
This section will describe how the mapping RecursiveDirectoryFilter.mfd, available in the ...
\MapForceExamples folder, was created and how recursive mappings are designed.
The screenshot below shows the finished mapping containing the recursive user-defined
function FilterDirectory, the aim being to filter out a list of the .xml files in the source file.
The source file that contains the file and directory data for this mapping is Directory.xml. This
XML file supplies the directory and file data in the hierarchical form you see below.
The XML schema file referenced by Directory.xml has a recursive element called "directory"
which allows for any number of subdirectories and files below the directory element.
© 2011 Altova GmbH
Altova MapForce 2011
206
How To... Filter, Transform, Aggregate
Altova MapForce 2011
Recursive user-defined mapping
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
Recursive user-defined mapping
207
12.16.1 Defining a recursive user-defined function
From the main mapping window:
1. Select Function | User defined Function to start designing the function and enter a
name e.g. FilterDirectory.
2. Make sure that you deselect the Inlined Use check box in the Implementation group,
to make the function recursive.
You are now in the FilterDirectory window where you create the user-defined function.
3. Select Function | Insert Input to insert an input component.
4. Give the component a name e.g. directory and click on the Complex Type (tree
structure) radio button.
5. Click the Choose button and select the directory.xsd file in the ...\MapForceExamples
directory.
6. Select Directory.xsd from the top pane and click OK to continue.
© 2011 Altova GmbH
Altova MapForce 2011
208
How To... Filter, Transform, Aggregate
Recursive user-defined mapping
7. Click OK again when asked to select the root item, which should be "directory".
8. Click OK again to insert the complex input parameter.
The user-defined function is shown below.
9. Delete the simple result output component, as we need to insert a complex output
component here.
10. Select Function | Insert Output... to insert an output component and use the same
method as outlined above, to make the output component, "directory", a complex type.
You now have two complex components, one input and the other output.
11. Select Component | Insert Input... and insert a component of type Simple type, and
enter a name e.g. SearchFor.
Altova MapForce 2011
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
Recursive user-defined mapping
209
Inserting the recursive user-defined function
At this point, all the necessary input and output components have been defined for the userdefined function. What we need to do now is insert the "unfinished" function into the current
user-defined function window. (You could do this at almost any point however.)
1. Find the FilterDirectory function in the user section of the Libraries window.
2. Click FilterDirectory then drag and drop it into the FilterDirectory window you have just
been working in.
Java Selected
The user-defined function now appears in the user-defined function window as a recursive
component.
3. Connect the directory, name and file items of the input component to the same items
in the output component.
4. Right click the connector between the file items and select "Insert Filter" to insert a filter
component.
5. Right click the on-true connector and select Copy-All from the context menu.
The connectors change appearance to Copy-All connectors.
© 2011 Altova GmbH
Altova MapForce 2011
210
How To... Filter, Transform, Aggregate
Recursive user-defined mapping
6. Insert a Contains function from the Core | String functions library.
7. Connect name to value and the SearchFor parameter to substring, then result to the
bool item of the filter.
8. Connect the SearchFor item of the input component to the SearchFor item of the userdefined function.
Defining the recursion
At this point, the mapping of a single directory recursion level is complete. Now we just need to
define how to process a subdirectory.
Making sure that the Toggle Autoconnect icon
is active in the icon bar:
1. Connect the lower directory item of the input component to the top directory item of
the recursive user-defined function.
Altova MapForce 2011
© 2011 Altova GmbH
How To... Filter, Transform, Aggregate
Recursive user-defined mapping
211
2. Connect the top output directory item of the user-defined function to the lower directory
item of the output component.
3. Right click the top connector, select Copy-All from the context menu and click OK when
prompted if you want to create Copy-All connection.
This completes the definition of the user-defined function in this window.
Click the Return to main mapping window icon,
there.
to continue defining the mapping
Main Mapping window
1. Drag the FilterDirectory function from the user section of the Libraries window, into the
main mapping area.
2. Use Insert | XML Schema file to insert Directory.xsd and select Directory.xml as the
instance file.
3. Use the same method to insert Directory.xsd and select Skip, to create the output
component.
© 2011 Altova GmbH
Altova MapForce 2011
212
How To... Filter, Transform, Aggregate
Recursive user-defined mapping
4. Insert a constant component, then a Input component e.g. SearchFor.
5. Create the connections as shown in the screenshot below.
6. When connecting the top-level connectors, directory to directory, on both sides of the
user-defined component, right click the connector and select Copy-All from the context
menu.
7. Click the Output tab to see the result of the mapping.
Notes:
Clicking the lowest "directory" item in the Directory component, opens a new level of recursion,
i.e. you will see a new directory | file | directory sublevel. Using the Copy-all connector
automatically uses all existing levels of recursion in the XML instance, you do not need expand
the recursion levels manually.
Altova MapForce 2011
© 2011 Altova GmbH
Chapter 13
StyleVision Power Stylesheets in Preview
214
StyleVision Power Stylesheets in Preview
13
StyleVision Power Stylesheets in Preview
MapForce is now able to preview/render XML Schema components using an associated
StyleVision Power Stylesheet (SPS). This means the target component data are previewed as
HTML, RTF, PDF, or Word 2007+ documents. If you are using the Enterprise edition of
StyleVision then charts will also be rendered in these previews.
To be able to preview components in this way, Altova StyleVision must be installed on your
computer; either as a standalone installation, or as part of Altova MissionKit.
StyleVision Power Stylesheets are created in StyleVision and are assigned to a component in
MapForce. You cannot edit or change the stylesheet in MapForce directly, but can open them
via MapForce in StyleVision. In the 64-bit edition of MapForce the Word 2007+ and RTF
previews are opened as a non-embedded application.
Additional tabs are added to the MapForce tab bar if StyleVision has been installed.
·
·
·
·
HTML
RTF - previews RTF
PDF - requires FOP version 0.93 or 1.0
Word 2007+ - previews MS Word documents from version 2007 and later
Please note:
The tabs available in MapForce depend on the installed version of StyleVision. All tabs
mentioned above are available in the Enterprise editions. Whenever you see these
extra tabs you know that an SPS file has been assigned to the component. The ...
\MapForceExamples folder contains many examples where this is the case.
The Professional edition of StyleVision restricts the tabs to HTML and RTF in
MapForce.
Note: if your mapping contains multiple linked components, i.e. a chained mapping, the SPS
preview will only be visible for those components containing an SPS entry, and where the
Preview button
of the component has been set as active.
Altova MapForce 2011
© 2011 Altova GmbH
StyleVision Power Stylesheets in Preview
© 2011 Altova GmbH
215
Altova MapForce 2011
216
StyleVision Power Stylesheets in Preview
13.1
Assigning an SPS file to a component
Assigning an SPS file to a component
The Tut-ExpReport-chain.mfd example shown below, is available in the ...
\MapForceExamples\Tutorial folder. For more information on chained mapping, as shown in the
example below, please see Chained mappings - Pass-through components.
To assign an SPS template to a MapForce component:
Having designed the SPS template in StyleVision, or obtained the template from a third party,
1. Double click the component title bar of the component you want to assign the SPS file
to, e.g. mf-ExpRep-Target.
2. Click the Browse button to select the StyleVision SPS file, then click OK.
Altova MapForce 2011
© 2011 Altova GmbH
StyleVision Power Stylesheets in Preview
Assigning an SPS file to a component
217
The HTML, RTF, PDF and Word 2007+ tabs appear to the right of the Output tab.
Clicking a tab renders the component data in the specific format.
Please note:
Clicking the Create... button in the Component Settings dialog box, prompts for an SPS
© 2011 Altova GmbH
Altova MapForce 2011
218
StyleVision Power Stylesheets in Preview
Assigning an SPS file to a component
file name and opens StyleVision allowing you to create a new SPS file. Double clicking
the same component once an SPS file has been assigned, shows the Create button as
Edit.
Altova MapForce 2011
© 2011 Altova GmbH
Chapter 14
Documenting mapping projects
220
Documenting mapping projects
14
Documenting mapping projects
The Generate Documentation command generates detailed documentation about your
mapping in HTML, MS Word, RTF or PDF. The documentation generated by this command can
be freely altered and used; permission from Altova to do so is not required.
Documentation is generated for components you select in the Generate Documentation dialog
box. You can either use the fixed design, or use a StyleVision SPS for the design. Using a
StyleVision SPS enables you to customize the design of the generated documentation. How to
do this is explained in the section, User-Defined Design.
Note:
To use an SPS to generate schema documentation, you must have StyleVision
installed on your machine. Related elements are typically hyperlinked in the onscreen
output, enabling you to navigate from component to component.
To generate documentation in MS Word format, you must have MS Word (version 2000
or later) installed.
The screenshot below shows a portion of the Lookup-standard.mfd file available in the ...
\MapForceExamples folder.
Having opened a mapping project e.g. Lookup-standard.mfd:
1. Select the menu option File | Generate Documentation.
This opens the "Generate documentation" dialog box. The screenshot below shows the
default dialog box settings.
Altova MapForce 2011
© 2011 Altova GmbH
Documenting mapping projects
221
Documentation Design
· Select "Use fixed design..." to use the built-in documentation template.
·
Select "Use user-defined..." to use a predefined StyleVision Power Stylesheet created
in StyleVision. The SPS files are available in the ...\My Documents\Altova
\MapForce2011\Documentation\MapForce\ folder.
·
Click Browse to browse for a predefined SPS file.
·
Click Edit to launch StyleVision and open the selected SPS in a StyleVision window.
The following predefined SPS stylesheets are available in the ...\Documentation\MapForce
folder:
·
FunctionCallGraph.sps - shows the call graph of the main mapping and any userdefined functions.
·
FunctionsUsedBy.sps - shows which functions are used directly, or indirectly, in the
mapping.
·
ImpactAnalysis.sps - lists every source and target node, and the route taken via
various functions, to the target node.
·
OverallDocumentation.sps - shows all nodes, connections, functions, and target
nodes. The output using this option outputs the maximum detail and is identical to the
built-in "fixed design..." output.
© 2011 Altova GmbH
Altova MapForce 2011
222
Documenting mapping projects
Output Format
· The output format is specified here: either HTML, Microsoft Word, RTF, or PDF.
Microsoft Word documents are created with the .doc file extension when generated
using a fixed design, and with a .docx file extension when generated using a
StyleVision SPS.
The PDF output format is only available if you use a StyleVision SPS to generate the
documentation.
·
Select "Split output to multiple files" if you would like separate input, output, constant
components, user-defined functions from the Library component documentation. In
fixed designs, links between multiple documents are created automatically.
·
The "Show Result File..." option is enabled for all output options. When checked, the
result files are displayed in Browser View (HTML output), MS Word (MS Word output),
and the default application for .rtf files (RTF output).
Path length limit
Allows you to define the maximum "path" length to be shown for items.
· E.g. .../ShortPO/LineItems/LineItem, which would be the maximum length for the default
setting 3.
Include
· Allows you to define the specific components to appear in the documentation.
Details
Allows you to set the specific details to appear in the documentation.
· selecting "Library Names" would insert the "core" prefix for functions.
· You can document both connected, as well as unconnected nodes.
Note:
The Check/Uncheck All buttons allow you to check/uncheck all check boxes of that group.
Having used the default settings shown above, clicking OK, prompts you for the name
of the output file and the location to which it should be saved. A portion of the fixed
design generated documentation is shown below. Note that this shows a single output
file.
This table shows the connections from the source component to the target component(s).
Altova MapForce 2011
© 2011 Altova GmbH
Documenting mapping projects
223
The sequence in which the components are documented is: Input, Output, Constant, Userdefined functions, then Library functions.
E.g. Input component ShortPO:
· The first two items ShortPO and ShortPO/CustomerNr are not connected to any item in
the target, thus the Connections column is empty.
· ShortPO/LineItems is directly connected to CompletePO/LineItems in the target.
· /LineItems/LineItem/ArticleNr has two connectors:
· directly to LineItem/Article/Number in the target
· to the User-defined function LookupArticle, with ArticleNr as the input parameter,
and Name as the output parameter of the user-defined function.
The contents of the user-defined function are shown below.
© 2011 Altova GmbH
Altova MapForce 2011
224
Documenting mapping projects
Output component CompletePO: This table shows the connections to the target component
from the source component(s).
·
·
·
The first two items CompletePO and CompletePO/Customer are not connected to any
item in the source component, thus the Connections column is empty.
CompletePO/LineItems is directly connected to ShortPO/LineItems in the source
component.
LineItem/Article/Name is connected to the User-defined function LookupArticle, with
LineItems/LineItem/ArticleNr as the source item.
Altova MapForce 2011
© 2011 Altova GmbH
Documenting mapping projects
© 2011 Altova GmbH
225
Altova MapForce 2011
226
Documenting mapping projects
14.1
Supplied SPS stylesheets
Supplied SPS stylesheets
Function Call Graphs - PersonListByBranchOffice.mfd
Functions Used By - PersonListByBranchOffice.mfd
Altova MapForce 2011
© 2011 Altova GmbH
Documenting mapping projects
Supplied SPS stylesheets
227
Impact Analysis - PersonListByBranchOffice.mfd
Overall Documentation - PersonListByBranchOffice.mfd
© 2011 Altova GmbH
Altova MapForce 2011
228
Documenting mapping projects
Altova MapForce 2011
Supplied SPS stylesheets
© 2011 Altova GmbH
Documenting mapping projects
14.2
User-Defined Design
229
User-Defined Design
Instead of the fixed design, you can create a customized design for the MapForce
documentation. The customized design is created in a StyleVision SPS. Note that there are 4
predefined SPS Stylesheets supplied with MapForce, please see Documenting mapping
projects.
Specifying the SPS to use for MapForce documentation
The SPS you wish to use for generating the documentation is specified in the Generate
Documentation dialog (accessed via File | Generate Documentation). Select the "Use
User-Defined Design..." radio button then click the dropdown arrow of the combo box and select
the file you want. The default selection is the OverallDocumentation.sps entry.
These predefined SPS files are located in the ...\Documentation\MapForce folder.
Please note:
To use an SPS to generate documentation, you must have StyleVision installed on your
machine.
Creating the SPS
A StyleVision Power Stylesheet (or SPS) is created using Altova's StyleVision product. An SPS
for generating MapForce documentation must be based on the XML Schema that specifies the
structure of the XML document that contains the MapForce documentation.
This schema is called MapForceDocumentation.xsd and is delivered with your MapForce
installation package. It is stored in the ...\My Documents\Altova\MapForce2011\Documentation
folder.
When creating the SPS design in StyleVision, nodes from the MapForceDocumentation.xsd
schema are placed in the design and assigned styles and properties. Note that the
MapForceDocumentation.xsd includes the Documentation.xsd file located in the folder above
it.
Additional components, such as links and images, can also be added to the SPS design. How
to create an SPS design in StyleVision is described in detail in the StyleVision user manual.
The advantage of using an SPS for generating schema documentation is that you have
complete control over the design of the documentation. Note also that PDF output of the
documentation is available only if an SPS is used; PDF output is not available if the fixed design
© 2011 Altova GmbH
Altova MapForce 2011
230
Documenting mapping projects
User-Defined Design
is used.
Altova MapForce 2011
© 2011 Altova GmbH
Chapter 15
Nil Values / Nillable
232
Nil Values / Nillable
15
Nil Values / Nillable
The XML Schema specification allows for elements to be valid without content (despite a
content type which does not allow empty content), if the nillable="true" attribute has been
defined for the specific element in the schema.
An attribute, xsi:nil="true" in the XML instance document, is used to indicate that the element
exists but that it has no content.
Note that this only applies to element values, and not attribute values. The element with xsi:
nil="true" may not have element or textual content, but may still have other attributes.
The nillable="true"
attribute is defined in the XML Schema and can be present in both the source and target
components.
The xsi:nil="true"
attribute is defined in the XML Instance file and is only present in the instance file.
The xsi:nil attribute is not displayed explicitly in the MapForce graphical mapping, because it is
handled automatically in most cases: A "nilled" node (that has the xsi:nil="true" attribute set)
exists, but its content does not exist.
Altova MapForce 2011
© 2011 Altova GmbH
Nil Values / Nillable
233
Nillable elements as mapping source
Whenever a mapping is reading data from nilled XML element, the xsi:nil attribute is
automatically checked. If the value of xsi:nil is true, the content will be treated as non-existant.
When creating a Target-driven mapping from a nillable source element to a nillable target
element with simple content (a single value with optional attributes, but without child elements),
where xsi:nil is set on a source element, the xsi:nil attribute is inserted into the target element
e.g. <OrderID xsi:nil="true"/>.
When creating a Copy-All mapping from a nillable source element to a nillable target element,
where xsi:nil is set on a source element, the xsi:nil attribute is inserted into the target element e.
g. <OrderID xsi:nil="true"/>.
Using functions
Connecting the "exists" function to a nilled source element will return "true" for all elements, due
to the fact that the element node actually exists, even if it has no content.
To check explicitly whether a source element has the xsi:nil attribute set to true, use the is-xsinil function. It returns true for "nilled" elements and false for other nodes.
Using functions that expect simple values (e.g. multiply, concat) on elements where xsi:nil has
been set, do not yield a result, as no element content is present and no value can be extracted.
These functions behave as if the source node did not exist.
To substitute a "nilled" (non-existing) source element value with something specific, use the
substitute-missing function.
Nillable elements as mapping target
When creating a Target-driven mapping from a nillable source element to a nillable target
element with simple content (a single value with optional additional attributes, but without child
elements), where xsi:nil is set on a source element, the xsi:nil attribute is inserted into the target
element e.g. <OrderID xsi:nil="true"/>.
If the xsi:nil="true" attribute has not been set in the XML source element, then the element
content is mapped to the target element in the usual fashion.
When mapping to a nillable target element with complex type (with child elements), the xsi:nil
attribute will not be written automatically, because MapForce cannot know at the time of writing
the element's attributes if any child elements will follow. Define a Copy-All connection to copy
the xsi:nil attribute from the source element.
When mapping an empty sequence to a target element, the element will not be created at all independent of its nillable designation.
Using functions
To force the creation of an empty target element with xsi:nil set to true, connect the set-xsi-nil
function directly to the target element. This works for target elements with simple and complex
types.
Use the substitute-missing-with-xsi-nil function to insert xsi:nil in the target if no value from
your mapping source is available. This can happen if the source node does not exist at all, or if
a calculation (e.g. multiply) involved a nilled source node and therefore yielded no result.
This function works only for nodes with simple content.
To create xsi:nil on an element of complex type depending on some condition, do the
© 2011 Altova GmbH
Altova MapForce 2011
234
Nil Values / Nillable
following:
·
·
·
·
·
Create the mapping as usual for the case where the target node contains content.
Insert a filter component into the connection to the target node, and define the condition
when there is any content.
Use the "duplicate input" function to duplicate your target node.
Connect the set-xsi-nil function via another filter component, to the duplicated target
node.
Insert a logical-not function to negate the condition, and connect it to the filter between
set-xsi-nil and the duplicated target node.
Altova MapForce 2011
© 2011 Altova GmbH
Chapter 16
HL7 v3.x to/from XML schema mapping
236
HL7 v3.x to/from XML schema mapping
16
HL7 v3.x to/from XML schema mapping
Support for HL7 version 3.x is automatically included in MapForce 2011 as it is XML based.
A separate installer for the HL7 V2.2 - V2.5.1 XML Schemas and configuration files, is available
on the MapForce Libraries page of the altova website. Select the Custom Setup in the installer,
to only install the HL7 V3 components and XML Schemas.
Location of HL7 XML Schemas after installation:
Windows XP machine:
Windows Vista machine:
Windows7 machine:
“C:\Program Files\Altova\Common2011\Schemas\ hl7v3“
“C:\Program Files\Altova\Common2011\Schemas\ hl7v3“
“C:\Program Files\Altova\Common2011\Schemas\ hl7v3“
If a 32-bit MapForce application is used on a 64-bit operating system, then the location is
“C:\Program Files(x86)\Altova\Common2011\Schemas\ hl7v3“.
HL7 documents can be used as source and target components in MapForce. This data can also
be mapped to any number of XML schema components.
Altova MapForce 2011
© 2011 Altova GmbH
Chapter 17
Libraries and Functions
238
Libraries and Functions
17
Libraries and Functions
The following sections describe how to define your own user-defined functions as well as
libraries for the various programming languages.
Defining User-defined functions
Adding custom XSLT and XQuery functions
Library Functions Reference
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
17.1
Defining User-defined functions
239
Defining User-defined functions
MapForce allows you to create user-defined functions visually, in the same way as in the main
main mapping window.
These functions are then available as function entries in the Libraries window (e.g First_Last),
and are used in the same way as the currently existing functions. This allows you to organize
your mapping into separate building blocks, and reuse them in the same, or different mappings.
XSLT Selected
User-defined functions are stored in the *.mfd file, along with the main mapping.
A user-defined function uses input and output components to pass information from the main
mapping (or another user-defined function) to the user-defined function and back.
User-defined functions can contain "local" source components (i.e that are within the
user-defined function itself) such as XML schemas, which are useful when implementing lookup
functions.
User-defined functions can contain any number of input and outputs where any of these can be
in the form of: simple values, or XML nodes.
User-defined functions are useful when:
· combining multiple processing functions into a single component, e.g. for formatting a
specific field or looking up a value
· reusing these components any number of times
· importing user-defined functions into other mappings (by loading the mapping file as a
library)
· using inline functions to break down a complex mapping into smaller parts that can be
edited individually
· mapping recursive schemas by creating recursive user-defined functions
User-defined functions can be either built from scratch, or from functions already available in
the mapping tab.
© 2011 Altova GmbH
Altova MapForce 2011
240
Libraries and Functions
Defining User-defined functions
This example uses the Tut-ExpReport.mfd file available in the ...\MapForceExamples\Tutorial\
folder.
To create a user-defined function from existing components:
1. Drag to mark both the concat and the constant components (you can also hold down
the CTRL key and click the functions individually).
2. Select the menu option Function | Create User-Defined Function from Selection.
3. Enter the name of the new user-defined function (First_Last).
Note: valid characters are: alphanumeric, a-z, A-Z, 0-9 as well as underscore "_",
hyphen/dash "-" and colon ":".
4. Use the Syntax and Detail fields to add extra information on the new function, and click
OK to confirm. The text you enter will appear as a tooltip when the cursor is placed over
the function.
The library name "user" is supplied as a default, you can of course define your own
library name in this field.
The individual elements that make up the function group appear in a tab with the
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Defining User-defined functions
241
function name. The new library "user" appears in the Libraries pane with the function
name "First_Last" below it.
XSLT Selected
Click the Home button
to return to the main mapping window. The components
have now been combined into a single function component called First_Last. The input
and output parameters have been automatically connected.
Note that inline user-defined functions are displayed with a dashed outline. See Inline
user-defined functions for more information.
Dragging the function name from the Libraries pane and dropping it in the mapping
window, allows you to use it anywhere in the current mapping. To use it in a different
mapping, please see Reusing user-defined functions
To open a user-defined function:
Do one of the following:
· Double-click the title bar of a user-defined function component
or
· Double-click the specific user-defined function in the Libraries window.
This displays the individual components inside the function in a tab of that name. Click
the Home button
© 2011 Altova GmbH
to return to the main mapping.
Altova MapForce 2011
242
Libraries and Functions
·
Defining User-defined functions
Double clicking a user-defined function of a different *.mfd file (in the main mapping
window) opens that MFD file in a new tab.
Navigating user-defined functions:
When navigating the various tabs (or user-defined function tabs) in MapForce, a history is
automatically generated which allows you to travel forward or backward through the various
tabs, by clicking the back/forward icons. The history is session-wide, allowing you to traverse
mutliple MFD files.
The Home button returns you to the main mapping tab from within the user-defined
function.
The Back button takes you back through your history
The Forward button moves you forward through your history
To delete a user-defined function from a library:
1. Double click the specific user-defined function in the Libraries window.
The user-defined function is visible in its tab.
2. Click the Erase button in the top right of the title bar to delete the function.
Reusing - exporting and importing User-defined functions:
User-defined functions, defined in one mapping, can be imported into any other mapping:
1. Click the Add/Remove Libraries button, at the base of the Libraries pane, click the
Add button and select a *.mfd file that contains the user-defined function(s) you want to
import.
The user-defined function now appear in the Libraries window (under "user" if that is the
default library you selected). You can of course enter anything in the "Library name"
field when defining the user-defined function.
2. Drag the imported function into the mapping to make use of it.
Library Names
Note: It is possible to use the same library name for user-defined functions in multiple
*.mfd files and/or custom libraries .
Functions from all available sources will appear under the same library name/header in
the Libraries pane. However, only the functions in the currently active document can be
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Defining User-defined functions
243
edited by double-clicking.
In the following example:
·
·
·
the function "hello" in the "helloworld" library is imported from a custom,
the function "Join" in the "helloworld" library is a user-defined function defined in the
current *.mfd file and
the function "MyUDF" in the "user" library is also a user-defined function defined in the
current *.mfd file
Java Selected
Note that possible changes in imported functions are applied to importing mappings
when saving the library *.mfd file.
Parameter order in user-defined functions
The parameter order within user-defined functions can be directly influenced:
· Input and output parameters are sorted by their position from top to bottom (from the
top left corner of the parameter component).
· If two parameters have the same vertical position, the leftmost takes precedence.
· In the unusual case that two parameters have exactly the same position, the internal
component ID is automatically used.
© 2011 Altova GmbH
Altova MapForce 2011
244
Libraries and Functions
Defining User-defined functions
Notes:
· Component positioning and resizing actions are "undoable".
·
Newly added input or output components, are created below the last input or output
component.
·
Complex and simple parameters can be mixed. The parameter order is derived from
the component positions.
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Defining User-defined functions
245
17.1.1 Function parameters
Function parameters are represented inside a user-defined function by input and output
components.
Input components/parameters: a, b, and
Output component/parameter: result
Input parameters are used to pass data from the main mapping into the user-defined function,
while output parameters are used to return data back to the main mapping. Note that
user-defined functions can also be called from other user-defined functions.
Simple and complex parameters
The input and output parameters of user-defined functions can be of various types:
·
·
Simple values, e.g. string or integer
Complex node trees, e.g. an XML element with attributes and child nodes
Input parameter POArtNr is a simple value of datatype "string"
Input parameter Articles is a complex XML document node tree
Output parameter Name is a simple value of type string
Note:
The user-defined functions shown above are all available in the
PersonListByBranchOffice.mfd file available in the ...\MapForceExamples folder.
Sequences
Sequences are data consisting of a range, or sequence, of values. Simple and complex userdefined parameters (input/output) can be defined as sequences in the component properties
dialog box.
Aggregate functions, e.g. min, max, avg, etc., can use this type of input to supply a single
© 2011 Altova GmbH
Altova MapForce 2011
246
Libraries and Functions
Defining User-defined functions
specific value from the input sequence. Please see Aggregate functions for more information.
When the "Input is a Sequence" check box is active, the component handles the input as a
sequence. When inactive, input is handled as a single value.
This type of input data, sequence or non-sequence, determines how often the function is
called.
·
When connected to a sequence parameter the user-defined function is called only
once and the complete sequence is passed into the user-defined function.
The screenshot shows the user-defined function "Calculate" of the "InputIsSequence.
mfd" mapping in the ...\MapForceExamples folder. The Temperatures input
component (shown below) is defined as a sequence.
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
·
Defining User-defined functions
247
When connected to a non-sequence parameter, the user-defined function is called
once for each single item in the sequence.
Please note:
The sequence setting of input/output parameters are ignored when the user-defined
function is of type inline.
Connecting an empty sequence to a non-sequence parameter has the result that the
function is not called at all!
This can happen if the source structure has optional items, or when a filter condition returns no
matching items. To avoid this, either use the substitute-missing function before the function
input to ensure that the sequence is never empty, or set the parameter to sequence, and add
handling for the empty sequence inside the function.
When a function passes a sequence of multiple values to its output component, and the output
component is not set to sequence, only the first result is used when the function is called.
© 2011 Altova GmbH
Altova MapForce 2011
248
Libraries and Functions
Defining User-defined functions
17.1.2 Inline and regular user-defined functions
Inline functions differ fundamentally from regular functions, in the way that they are
implemented when code is generated.
·
The code for inline type functions is inserted at all locations where the user-defined
functions are called/used
·
The code of a regular function is implemented as a function call.
Inline functions thus behave as if they had been replaced by their implementation. That
makes them ideal for breaking down a complex mapping into smaller encapsulated
parts.
Please note:
using inline functions can significantly increase the amount of generated program
code! The user-defined function code is actually inserted at all locations where the
function is called/used, and thus increases the code size substantially - as opposed to
using a regular function.
INLINE user-defined functions are shown with a dashed outline:
Inline user-defined functions support:
· Multiple output components within a function
do not support:
· The setting of a priority context on a parameter
· Recursive calls to an inline user-defined function
REGULAR user-defined functions i.e. non-inline functions are shown with a solid outline:
Regular (non-inline) user-defined functions support:
· Only a single output component within a function
· Recursive calls (where the exit condition must be supplied, e.g. use an If-Else
condition where one branch, or value, exits the recursion)
· Setting a priority context on a parameter
Please note:
Although regular functions do not support multiple output components, they can be
created in this type of function. However, an error message appears when you try to
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Defining User-defined functions
249
generate code, or preview the result of the mapping.
If you are not using recursion in your function, you can change the type of the function
to "inline".
do not support:
· Direct connection of filters to simple non-sequence input components
· Sequence or aggregate functions on simple input components (like exists, substitutemissing, sum, group-by, ...)
Code generation
The implementation of a regular user-defined function is generated only once as a
callable XSLT template or function. Each user-defined function component generates
code for a function call, where inputs are passed as parameters, and the output is the
function (component) return value.
At runtime, all the input parameter values are evaluated first, then the function is called
for each occurrence of the input data. See Function parameters for details about this
process.
To change the user-defined function "type":
1. Double click the user-defined function to see its constituent components.
2. Select the menu option Function | Function settings and click the "Inlined use"
checkbox.
User-defined functions and Copy-all connections
When creating Copy-all connections between a schema and a complex user-defined function
parameter, the two components must be based on the same schema! It is not necessary that
they both have the same root elements however. Please see "Complex output components defining" for an example.
© 2011 Altova GmbH
Altova MapForce 2011
250
Libraries and Functions
Defining User-defined functions
17.1.3 Creating a simple look-up function
This example is provided as the lookup-standard.mfd file available in the
...\MapForceExamples folder.
Aim:
To create a generic look-up function that:
· supplies Articles/Number data from the Articles XML file, to be compared to Article
numbers of a different XML file, ShortPO in this case.
·
·
·
Insert the ShortPO.xsd and assign ShortPO.xml as the source XML file.
Insert the CompletePO.xsd schema file, and select CompletePO as the root element.
Insert a new user-defined function using the method described below.
To create a user-defined function from scratch:
1. Select the menu option Function | Create User-defined function.
2. Enter the name of the function e.g. LookupArticle.
3. Uncheck the "Inlined use" checkbox and click OK to confirm
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Defining User-defined functions
251
A tab only containing only one item, an output function currently called "result", is
displayed.
Java Selected
This is the working area used to define the user-defined function.
A new library has been created in the Libraries pane with the name "user" and the
function name "LookupArticle".
3. Click the Insert Schema/XML file icon
to insert the Articles schema and select the
XML file of the same name to act as the data source.
4. Click the Insert input component icon
to insert an input component.
5. Enter the name of the input parameter, ArticleNr in this case, and click OK.
© 2011 Altova GmbH
Altova MapForce 2011
252
Libraries and Functions
Defining User-defined functions
This component acts as a data input to the user-defined function and supplies the input
icon of the user-defined function.
6. Insert an "equal" component by dragging it from the core library/logical functions group.
7. Insert a filter component by clicking the Insert Filter icon
in the toolbar.
Use the diagram below as an aid to creating the mappings in the user-defined function,
please take note of the following:
8 Right click the a parameter and select Priority context from the pop up menu.
9. Double click the output function and enter the name of the output parameter, in this
case "Name".
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Defining User-defined functions
253
This ends the definition of the user-defined function.
Please note:
Double clicking the input and output functions opens a dialog box in which you can
change the name and datatype of the input parameter, as well as define if the function
is to have an input icon (Input is required) and additionally if it should be defined as a
sequence.
·
·
·
·
This user-defined function:
has one input function, ArticleNr, which will receive data from the ShortPO XML file.
compares the ShortPO ArticleNr, with the Article/Number from the Articles XML
instance file, inserted into the user-defined function for this purpose.
uses a filter component to forward the Article/Name records to the output component, if
the comparison returns true.
has one output function, Name, which will forward the Article Name records to the
CompletePO XML file.
10. Click the Home icon
to return to the main mapping.
The LookupArticle user-defined function, is now available under the user library.
Java Selected
11. Drag the LookupArticle function into the Mapping window.
·
·
The user-defined function is displayed:
with its name "LookupArticle" in the title/function bar,
with named input and output icons.
© 2011 Altova GmbH
Altova MapForce 2011
254
Libraries and Functions
Defining User-defined functions
10. Create the connections displayed in the graphic below and click the Output tab to see
the result of the mapping.
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Defining User-defined functions
255
17.1.4 Complex user-defined function - XML node as input
This example is provided as the lookup-udf-in.mfd file available in the ...\MapForceExamples
folder. What this section will show, is how to define an inline user-defined function that contains
a complex input component.
Note that the user-defined function "FindArticle" consists of two halves.
A left half which contains the input parameters:
· a simple input parameter POArtNr
· a complex input component Articles, with mappings directly to its XML child nodes
A right half which contains:
· a simple output parameter called "Name".
The screenshot below shows the constituent components of the user-defined function, the two
input components at left and the output component at right.
© 2011 Altova GmbH
Altova MapForce 2011
256
Libraries and Functions
Defining User-defined functions
Complex input components - defining
Defining complex input components:
1. Create a user-defined function in the usual manner, i.e. Function | Create
User-Defined function and click OK to confirm. Note that the Inlined use check box is
automatically selected.
2. Click the Insert input component icon
in the icon bar.
3. Enter the name of the input component into the Name field.
4. Click the Complex type (tree structure) radio button, then click the "Choose" button
next to the Structure field.
This opens another dialog box.
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Defining User-defined functions
257
The top list box displays the existing components in the mapping (three schemas if you
opened the example mapping). Note that this list contains all of the components that
have been inserted into the active mapping: e.g. XML schema file.
The lower list box allows you to select a new complex data structure i.e. XML Schema
file.
5. Click "Insert a new structure... " radio button, select the XML Schema Structure entry,
and click OK to continue.
6. Select Articles.xsd from the "Open" dialog box.
7. Click the element that you would like to become the root element in the component, e.g.
Articles, and click OK, then OK again to close both dialog boxes.
The Articles component is inserted into the user-defined function. Please note the input
© 2011 Altova GmbH
Altova MapForce 2011
258
Libraries and Functions
Defining User-defined functions
icon
to the left of the component name. This shows that the component is used as a
complex input component.
8. Insert the rest of the components as shown in the screenshot below, namely: a second
"simple" input component (called POArtNr), filter, equal and output component (called
Name), and connect them as shown.
Please note:
· The Articles input component receives its data from outside of the user-defined
function. Input icons that allow mapping to this component, are available there.
· An XML instance file to provide data from within the user-defined function, cannot be
assigned to a complex input component.
· The other input component POArtNr, supplies the ShortPO article number data to which
the Article | Number is compared.
· The filter component filters out the records where both numbers are identical, and
passes them on to the output component.
10. Click the Home icon
to return to the mapping.
11. Drag the newly created user-defined component from the Libraries pane into the
mapping.
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Defining User-defined functions
259
Java Selected
12. Create the connections as shown in the screenshot below.
The left half contains the input parameters to which items from two schema/xml files are
mapped:
· ShortPO supplies the data for the input component POArtNr.
· Articles supplies the data for the complex input component. The Articles.xml instance
file was assigned to the Articles schema file when the component was inserted.
· The complex input component Articles with its XML child nodes, to which data has
been mapped from the Articles component.
The right half contains:
· a simple output parameter called "Name", which passes on the filtered line items which
have the same Article number, to the Name item of Complete PO.
© 2011 Altova GmbH
Altova MapForce 2011
260
Libraries and Functions
Defining User-defined functions
Please note:
When creating Copy-all connections between a schema and a user-defined function
parameter, the two components must be based on the same schema! It is not necessary that
they both have the same root elements however.
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Defining User-defined functions
261
17.1.5 Complex user-defined function - XML node as output
This example is provided as the lookup-udf-out.mfd file available in the
...\MapForceExamples folder. What this section will show is how to define an inline
user-defined function that allows a complex output component.
Note that the user-defined function FindArticle consists of two halves.
A left half which contains the input parameter:
· a simple input parameter POArtNr
A right half which contains:
· a complex output component Article (CompletePO) with its XML child nodes mapped
to CompletePO.
The screenshot below shows the constituent components of the user-defined function, the input
components at left and the complex output component at right.
Complex output components - defining
Defining complex output components:
1. Create a user-defined function in the usual manner, i.e. Function | Create
User-Defined function name it FindArticle, and click OK to confirm. Note that the
Inline... option is automatically selected.
© 2011 Altova GmbH
Altova MapForce 2011
262
Libraries and Functions
2. Click the Insert Output icon
Defining User-defined functions
in the icon bar, and enter a name e.g. CompletePO.
3. Click the Complex type... radio button, then click the "Choose" button.
This opens another dialog box.
The top list box displays the existing components in the mapping, (three schemas if
you opened the example file). Note that this list contains all of the components that
have been inserted into the active mapping: e.g. XML Schema file.
The lower list box allows you to select a new complex data structure i.e. XML Schema
file.
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Defining User-defined functions
263
4. Click "Insert new structure... " radio button, select the XML Schema Structure entry,
and click OK to continue.
5. Select the CompletePO.xsd from the "Open" dialog box.
6. Click the element that you would like to become the root element in the component,
e.g. Article, and click OK, then OK again to close the dialog boxes.
The CompletePO component is inserted into the user-defined function. Please note the
output icon
to the left of the component name. This shows that the component is
used as a complex output component.
© 2011 Altova GmbH
Altova MapForce 2011
264
Libraries and Functions
Defining User-defined functions
7. Insert the Articles schema/XML file into the user-defined function and assign the
Articles.xml as the XML instance.
8. Insert the rest of the components as shown in the screenshot below, namely: the
"simple" input components (POArtNr), filter, equal and multiply components, and
connect them as shown.
Please note:
· The Articles component receives its data from the Articles.xml instance file, within the
user-defined function.
· The input components supply the POArtNr (article number) and Amount data to which
the Articles | Number & Price are compared.
· The filter component filters out the records where both numbers are identical, and
passes them on to the CompletePO output component.
9. Click the Home icon
to return to the mapping.
10. Drag the newly created user-defined component from the Libraries pane into the
mapping.
Java Selected
11. Create the connections as shown in the screenshot below.
Having created the Article (CompletePO) connector to the target, right click it and
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Defining User-defined functions
265
select "Copy-all" from the context menu. The rest of the connectors are automatically
generated, and are highlighted in the screenshot below.
Please note:
When creating Copy-all connections between a schema and a user-defined function of type
"Inline", the two components must be based on the same schema! It is not necessary that they
both have the same root elements however.
The left half contains the input parameter to which a single item is mapped:
· ShortPO supplies the article number to the POArtNr input component.
The right half contains:
· a complex output component called "Article (CompletePO)" with its XML child nodes,
which maps the filtered items, of the same Article number, to CompletePO.
© 2011 Altova GmbH
Altova MapForce 2011
266
Libraries and Functions
Defining User-defined functions
17.1.6 User-defined function - example
The PersonListByBranchOffice.mfd file available in the ...\MapForceExamples folder,
describes the following features in greater detail:
·
·
·
·
Nested User-defined functions e.g. LookupPerson
Look-up functions that generate a string output e.g. LookupPerson
Optional input-parameters which can also supply a default value e.g. the EqualAnd
component (contained in the LookupPerson component)
Configurable input parameters, which can also double as a command line
parameter(s) when executing the generated mapping code!
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Defining User-defined functions
267
Configurable input parameters
The input component (OfficeName) receives data supplied when a mapping is executed. This is
possible in two ways:
·
·
as a command line parameter when executing the generated code, e.g. Mapping.exe
/OfficeName "Nanonull Partners, Inc."
as a preview value when using the Built-in execution engine to preview the data in the
Output window.
To define the Input value:
1. Double click the input component and enter a different value in the "Value" text box of
the Preview Mode group e.g. "Nanonull Partners, Inc.", and click OK to confirm.
2. Click the Output tab to see the effect.
A different set of persons are now displayed.
Please note that the data entered in this dialog box is only used in "preview" mode i.e.
when clicking the Output tab. If a value is not entered, or the check box is deactivated,
then the data mapped to the input icon "default" is used.
Please see Input values, overrides and command line parameters for more information.
© 2011 Altova GmbH
Altova MapForce 2011
268
Libraries and Functions
Defining User-defined functions
LookupPerson component
Double clicking this user-defined component displays its constituent components shown below.
What this component does is:
·
Compares the Office, First, and Last names of BranchOffices.xml, with the same fields
of the Altova_Hierarchical.xml file, using the input components and the EqualAnd
user-defined components.
·
Combines the Email, PhoneExt and Title items using the Person2Details user-defined
function
·
Passes on the combined person data to the output component if the previous
EqualAnd comparisons are all true (i.e. supplied "true" to the filter component).
A user-defined function always outputs a value, which may even be an empty string! This would
be the case if the filter component bool value is false. Only an empty string would be output
instead of data supplied by the Person2Details component.
·
·
·
The three input components, Office_Name, First_Name, Last_Name, receive their
data from the BranchOffices.xml file.
The EqualAnd component compares two values and provides an optional comparison
value, as well as a default value.
Person2Details combines three person fields and passes on the result to the filter
component.
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Defining User-defined functions
269
EqualAnd component
Double clicking this user-defined component displays its constituent components shown below.
What this component does is:
·
·
·
Compare two input parameters a and b, and pass the result on to the logical-and
component. Note that the b parameter has been defined as the priority context (right
click the icon to do so). This ensures that the person data of the specific office, supplied
by the input parameter a, is processed first.
Logical-and the result of the first comparison, with an optional input parameter, "and".
Pass on the boolean value of this comparison to the output parameter.
Optional parameters
Double clicking the "and" parameter, of the EqualAnd user-defined function shown above,
allows you to make parameters optional, by unchecking the "Input is required" check box.
If "Input is required" is unchecked, then:
·
·
·
A mapping connector is not required for the input icon of this user-defined function, e.g.
the and parameter of the first EqualAnd function, does not have an input connector.
The input icon has a dashed outline to show this visually.
A default value can be supplied by connecting a component, within the user-defined
function e.g. using a constant component containing the value "true".
A mapping from another item, mapped to the optional Input, takes precedence over the
default value. E.g. the "and" parameter of second EqualAnd function, receives input
data from the "result" parameter of the first EqualAnd user-defined function.
© 2011 Altova GmbH
Altova MapForce 2011
270
Libraries and Functions
Defining User-defined functions
Person2Details component
Double clicking this user-defined component displays its constituent components shown below.
What this component does is:
·
·
Concatenate three inputs and pass on the result string to the output parameter.
Double clicking an output parameter allows you to change the parameter name
(Details), and select the datatype (String).
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
17.2
Adding custom XSLT and XQuery functions
271
Adding custom XSLT and XQuery functions
MapForce allows you to extend the installed XSLT function libraries with your own custom
functions. This option is made available when you select XSLT as the output, by clicking the
XSLT icon, or selecting Output | XSLT 1.0.
XSLT files appear as libraries, and display all named templates as functions below the library
name.
·
·
·
·
·
·
Functions must be declared as Named Templates conforming to the XSLT 1.0
specification in the XSLT file.
If the imported XSLT file imports or includes other XSLT files, then these XSLT files
and functions will be imported as well.
Each named template appears as a function below each library name.
The amount of mappable input icons depends on the number of parameters used in the
template call; optional parameters are also supported.
Updates to imported XSLT files occur at program start or whenever the files change.
Namespaces are supported
Please note:
When writing named templates please make sure that the XPath statements used in
the template are bound to the correct namespace(s). The namespace bindings of the
mapping can be viewed by clicking the XSLT tab. Please see: the XSLT 1.0
implementation specific document for more information.
© 2011 Altova GmbH
Altova MapForce 2011
272
Libraries and Functions
Adding custom XSLT and XQuery functions
17.2.1 Adding custom XSLT 1.0 functions
The files needed for the simple example shown below, are available in the
...\MapForceExamples directory.
·
·
·
·
Name-splitter.xslt
Name-splitter.xml (the XML instance file for Customers.xsd)
Customers.xsd
CompletePO.xsd
Please see: Aggregate functions for an additional example of using named templates to sum
nodes.
To add a custom XSLT function:
1. Create an XSLT file that achieves the transformation/result you want.
The example below, Name-splitter.xslt, shows a named template called "tokenize"
with a single parameter "string". What the template does, is work through an input string
and separate capitalized characters with a space for each occurrence.
2. Click the Add/Remove Libraries button, and then click the Add button in the following
dialog box.
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Adding custom XSLT and XQuery functions
273
XSLT Selected
3. Select the XSL, or XSLT file, that contains the named template you want to act as a
function, in this case Name-splitter.xslt. The XSLT file appears in the Libraries tab.
4. Click OK to insert the new function.
© 2011 Altova GmbH
Altova MapForce 2011
274
Libraries and Functions
Adding custom XSLT and XQuery functions
XSLT Selected
The XSLT file name appears in the library window, along with the function(s) defined as
named templates, below it. In this example Name-splitter with the tokenize function.
5. Drag the function into the Mapping window, to use it in you current mapping, and map
the necessary items, as show in the screenshot below.
XSLT Selected
6. Click the XSLT tab to see the generated XSLT code.
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Adding custom XSLT and XQuery functions
275
Please note:
As soon as a named template is used in a mapping, the XSLT file containing the
named template is included in the generated XSLT code (xsl:include href...), and is
called using the command xsl:call-template.
7. Click the Output tab to see the result of the mapping.
To delete custom XSLT functions:
1. Click the Add/Remove Libraries button.
2. Click to the specific XSLT library name in the Libraries tab
3. Click the Delete button, then click OK to confirm.
© 2011 Altova GmbH
Altova MapForce 2011
276
Libraries and Functions
Adding custom XSLT and XQuery functions
17.2.2 Adding custom XSLT 2.0 functions
MapForce also allows you to import XSLT 2.0 functions that occur in an XSLT 2.0 document in
the form:
<xsl:function name="MyFunction">
Please see: the XSLT 2.0 implementation specific document for more information, as well as
Aggregate functions for an additional example of using named templates to sum nodes.
Datatypes in XPath 2.0
If your XML document references an XML Schema and is valid according to it, you must
explicitly construct or cast datatypes that are not implicitly converted to the required datatype by
an operation.
In the XPath 2.0 Data Model used by the Altova XSLT 2.0 Engine, all atomized node values
from the XML document are assigned the xs:untypedAtomic datatype. The
xs:untypedAtomic type works well with implicit type conversions.
For example,
·
·
·
the expression xs:untypedAtomic("1") + 1 results in a value of 2 because the
xdt:untypedAtomic value is implicitly promoted to xs:double by the addition
operator.
Arithmetic operators implicitly promote operands to xs:double.
Value comparison operators promote operands to xs:string before comparing.
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Adding custom XSLT and XQuery functions
277
17.2.3 Aggregate functions - summing nodes in XSLT1 and 2
This section describes the method you can use to process multiple nodes of an XML instance
document and have the result mapped as a single value to a target item. The files used in this
example are available in the ...\MapForceExamples\Tutorial\ folder and consists of:
Summing-nodes.mfd
input.xml
input.xsd and output.xsd
Summing-nodes.xslt
mapping file
input XML file
source and target schema files
xslt file containing a named template to sum the
individual nodes
There are two separate methods of creating and using aggregate functions:
·
·
Using the aggregate functions available in the core library of the Library pane
Using a Named Template.
Aggregate functions - library
Depending on the XSLT library you select, XSLT 1 or XSLT 2, different aggregate functions are
available in the core library. XSLT 1 supports count and sum, while XSLT 2 supports avg, count,
max, min, string-join and sum.
Drag the aggregate function that you use from the library into the mapping area and connect the
source and target components as shown in the screenshot below.
For more information on this type of aggregate function, please also see Aggregate functions.
Aggregate function - Named template
The screenshot below shows the XML input file. The aim of the example is to sum the Price
fields of any number of products, in this case products A and B.
© 2011 Altova GmbH
Altova MapForce 2011
278
Libraries and Functions
Adding custom XSLT and XQuery functions
The screenshot below shows the XSLT stylesheet which uses the named template "Total" and
a single parameter "string". What the template does, is work through the XML input file and sum
all the values obtained by the XPath expression /Product/Price, in the document.
1. Click the Add/Remove Libraries button, and select the Libraries tab of the Options
dialog box.
2. Click the Add button and select the Summing-nodes.xslt file from the
...\MapForceExamples\Tutorial\ folder.
3. Drag in the Total function from the newly created Summing-nodes library and create the
mappings as shown below.
4. Click the Output tab to preview the mapping result.
The two Price fields of both products have been added and placed into the Total field.
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Adding custom XSLT and XQuery functions
279
To sum the nodes in XSLT 2.0:
· Change the stylesheet declaration in the template to ... version="2.0".
© 2011 Altova GmbH
Altova MapForce 2011
280
Libraries and Functions
17.3
Functions Reference
Functions Reference
This reference section describes all the functions that are available in the Libraries pane for
each of the supported languages: XSLT1, XSLT2.
The following libraries are currently available:
core
xpath2
xslt
Extendable functions
Several functions available in the function libraries are extendable: for e.g. the concat,
"logical-and", "logical-or", and IF-ELSE functions. The parameters of these types of function can
be inserted/appended and deleted at will.
Clicking the "plus" icon inserts or appends the same type of parameter, while clicking the check
mark deletes the parameter.
Please note: "dropping" a connector on the "plus" symbol, automatically inserts/appends the
parameter and connects it.
The IF test parameters, of the IF-Else function can be extended in the same way.
Placing the mouse cursor over the function title bar, pops up a tooltip describing the function.
Placing it over a parameter (any input or result parameter) displays the datatype of the
argument in a tooltip.
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Functions Reference
281
17.3.1 core
The core library supplies the most useful functions for all languages. The sequence functions
are not available if XSLT (XSLT 1.0) has been selected.
Core library
· aggregates
· conversion functions
· logical functions
· math functions
· node functions
· sequence functions
· string functions
aggregates
Aggregate functions perform operations on a set, or sequence, of input values. The input data
for min, max, sum and avg is converted to the decimal datatype for processing.
·
·
·
The input values must be connected to the values parameter of the function.
A context node (item) can be connected to the parent-context parameter to override
the default context from which the input sequence is taken. This also means that the
parent-context parameter is optional!
The result of the function is connected to the specific target item.
The mapping shown below is available as Aggregates.mfd in the ...\Tutorial folder and shows
how these functions are used.
Aggregate functions have two input items.
· values is connected to the source item that provides the data, in this case Number.
· parent-context is connected to the item you want to iterate over, i.e. the context, in this
case over all Customers. The parameter is, howerver, optional.
© 2011 Altova GmbH
Altova MapForce 2011
282
Libraries and Functions
Functions Reference
The input instance in this case is an XML file containing the following data:
·
·
The source data supplied to the values item is the number sequence 2,4,6,8.
The output component in this case is a simple text file.
Clicking the Output tab for the above mapping delivers the following result:
min=2, max=8, count=4, sum=20 and avg=5.
avg
Returns the average value of all values within the input sequence. The average of an empty set
is an empty set. Not available in XSLT1.
count
Returns the number of individual items making up the input sequence. The count of an empty
set is zero. Limited functionality in XSLT1.
max
Returns the maximum value of all values in the input sequence. The maximum of an empty set
is an empty set. Not available in XSLT1.
min
Returns the minumum value of all values in the input sequence. The minimum of an empty set
is an empty set. Not available in XSLT1.
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Functions Reference
283
string-join
Concatenates all the values of the input sequence into one string delimited by whatever string
you choose to use as the delimiter. The string-join of an empty set is the empty string. Not
available in XSLT1.
The example below contains four separate customer numbers 2 4 6 and 8. The constant
character supplies a hash character "#" as the delimiter.
Result = 2#4#6#8
If you do not supply a delimiter, then the default is an empty string, i.e. no delimiter of any sort.
Result = 2468.
sum
Returns the arithmetic sum of all values in the input sequence. The sum of an empty set is zero.
Not available in XSLT1.
conversion functions
To support explicit data type conversion, the type conversion functions "boolean", "number" and
"string" are available in the conversion function library. Note that in most cases, MapForce
creates necessary conversions automatically and these functions need to be used only in
special cases.
input parameters = arg
output parameter = result
boolean
Converts an input numeric value into a boolean (as well as a string to numeric - true to 1). E.g. 0
to "false", or 1 to "true", for further use with logical functions (equal, greater etc.) filters, or if-else
functions.
© 2011 Altova GmbH
Altova MapForce 2011
284
Libraries and Functions
Functions Reference
format-dateTime
Converts a dateTime into a string.
Argument
Description
value
The dateTime to be formatted
format
A format string identifying the way in which the dateTime is to be
formatted
Note:
If the function’s output (i.e. result) is connected to a node of type other than string, the
formatting may be lost as the value is cast to the target type. This automatic cast can be
disabled by unchecking the "Cast target values to target types" check box in the component
settings of the target component.
Format String
The format argument consists of a string containing so-called variable markers enclosed in
square brackets. Characters outside the square brackets are literal characters to be copied into
the result. If square brackets are needed as literal characters in the result, then they should be
doubled.
Each variable marker consists of a component specifier identifying which component of the date
or time is to be displayed, an optional formatting modifier, another optional presentation modifier
and an optional width modifier, preceded by a comma if it is present.
format := (literal | argument)*
argument := [component(format)?(presentation)?(width)?]
width := , min-width ("-" max-width)?
The components are:
Specifier Description
Default Presentation
Y
year (absolute value)
four digits (2010)
M
month of the year
1-12
D
day of month
1-31
d
day of year
1-366
F
day of week
name of the day (language
dependent)
W
week of the year
1-53
w
week of month
1-5
H
hour (24 hours)
0-23
h
hour (12 hour)
1-12
P
A.M. or P.M.
alphabetic (language dependent)
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Functions Reference
m
minutes in hour
00-59
s
seconds in minute
00-59
f
fractional seconds
numeric, one decimal place
Z
timezone as a time offset from
UTC
+08:00 or PST with alphabetic
modifier
z
timezone as a time offset using
GMT
GMT+n
The presentation modifier:
Specifier
Description
o
Indicates ordinal
numbering
285
Example
[1o] gives 1st, 2nd, 3rd, 4th,...
The formatting modifier:
Character Description
Example
1
decimal numeric format with no leading
zeros: 1, 2, 3, ...
1, 2, 3
01
decimal format, two digits: 01, 02, 03, ...
01, 02, 03
i
roman numerals
i, ii, iii, iv
I
roman numerals, upper case
I, II, III, IV
N
name of component, upper case
MONDAY,
TUESDAY
n
name of component, lower case
monday, tuesday
Nn
name of component, title case
Monday, Tuesday
W
number expressed, upper case (not for
parsing)
ONE, TWO,
THREE
w
number expressed, lower case (not for
parsing)
one, two, three
Ww
number expressed, title case (not for
parsing)
One, Two, Three
1) N, n, and Nn modifiers only support the following components: M, d, D.
The width modifier, if present, is introduced by a comma. It takes the form:
, min-width ("-" max-width)?
Supported examples
DateTime
format String
Result
2003-11-03T00: [D]/[M]/[Y]
00:00
3/11/2003
2003-11-03T00: [Y]-[M,2]-[D,2]
00:00
2003-11-03
© 2011 Altova GmbH
Altova MapForce 2011
286
Libraries and Functions
Functions Reference
2003-11-03T00: [Y]-[M,2]-[D,2]
00:00
2003-11-03
2003-11-03T00: [Y]-[M,2]-[D,2] [H,2]:[m]:[s]
00:00
2003-11-03 00:00:00
2010-06-02T08: [Y] [MNn] [D01] [F,3-3] [d]
02
[H]:[m]:[s].[f]
2010 June 02 Wed 153
8:02:12.054
2010-06-02T08: [Y] [MNn] [D01] [F,3-3] [d]
02
[H]:[m]:[s].[f] [z]
2010 June 02 Wed 153
8:02:12.054 GMT+02:00
2010-06-02T08: [Y] [MNn] [D1] [F] [H]:[m]:[s].[f]
02
[Z]
2010 June 2 Wednesday
8:02:12.054 +02:00
2010-06-02T08: [Y] [MNn] [D] [F,3-3]
02
[H01]:[m]:[s]
2010 June 2 Wed
08:02:12
format-number
Available for XSLT 1.0, XSLT 2.0, Java, C#, C++ and Built-in execution engine.
Argument
Description
value
The number to be formatted
format
A format string that identifies the way in which the
number is to be formatted
decimal-point-format
The character to be used as the decimal point
character. Default is the '.' character (optional)
grouping-separator
The separator/delimiter used to separate groups of
numbers. Default is the "," character (optional)
Note:
If the function’s output (i.e. result) is connected to a node of type other than string, the
formatting may be lost as the value is cast to the target type. This automatic cast can be
disabled by unchecking the "Cast target values to target types" check box in the component
settings of the target component.
format
A format string identifies the way in which the number is to be formatted.
Format:
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Functions Reference
287
format := subformat (;subformat)?
subformat := (prefix)? integer (.fraction)? (suffix)?
prefix := any characters except special characters
suffix := any characters except special characters
integer := (#)* (0)* ( allowing ',' to appear)
fraction := (0)* (#)* (allowing ',' to appear)
The first subformat is used for formatting positive numbers, and the second subformat for
negative numbers. If only one subformat is specified, then the same subformat will be used for
negative numbers, but with a minus sign added before the prefix.
Special Character
default
Description
zero-digit
0
A digit will always appear at this point in
the result
digit
#
A digit will appear at this point in the
result string unless it is a redundant
leading or trailing zero
decimal-point
.
Separates the integer and the fraction
part of the number.
grouping-seperator
,
Seperates groups of digits.
percent-sign
%
Multiplies the number by 100 and shows
it as a percentage
per-mille
‰
Multiplies the number by 1000 and
shows it as per-mille
The characters used for decimal-point-character and grouping-separator are always "." and ","
respectively. They can however, be changed in the formatted output, by mapping constants to
these nodes.
The result of the format number function shown above.
· The decimal-point character was changed to a "+".
· The grouping separator was changed to a "-"
Rounding
The rounding method used for this function is half up, e.g. rounds up if the fraction is > or equal
to 0.5. Rounds down if fraction is <0.5.
© 2011 Altova GmbH
Altova MapForce 2011
288
Libraries and Functions
Functions Reference
Number
format String
Result
1234.5
#,##0.00
1,234.50
123.456
#,##0.00
123.46
1000000
#,##0.00
1,000,000.00
-59
#,##0.00
-59.00
1234
###0.0###
1234.0
1234.5
###0.0###
1234.5
.00025
###0.0###
0.0003
.00035
###0.0###
0.0004
0.25
#00%
25%
0.736
#00%
74%
1
#00%
100%
-42
#00%
-4200%
-3.12
#.00;(#.00)
(3.12)
-3.12
#.00;#.00CR
3.12CR
number
Converts an input string into a number. Also converts a boolean input to a number.
parse-date
Available for Java, C#, C++, and the Built-in execution engine.
Converts a string into an date, while ignoring the time component.
parse-dateTime
Available for Java, C#, C++, and the Built-in execution engine.
Converts a string into an dateTime.
Argument
Description
value
The string containing the date/time
format
The picture string which defines how value is currently
formatted
The components are:
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Functions Reference
Specifier Description
Default Presentation
Y
year (absolute value)
four digits (2010)
M
month of the year
1-12
D
day of month
1-31
d
day of year
1-366
H
hour (24 hours)
0-23
h
hour (12 hour)
1-12
P
A.M. or P.M.
alphabetic (language dependent)
m
minutes in hour
00-59
s
seconds in minute
00-59
f
fractional seconds
numeric, one decimal place
Z
timezone as a time offset from
UTC
+08:00 or PST with alphabetic
modifier
z
timezone as a time offset using
GMT
GMT+n
The formatting modifier:
Character Description
289
Example
1
decimal numeric format with no leading
zeros: 1, 2, 3, ...
1, 2, 3
01
decimal format, two digits: 01, 02, 03, ...
01, 02, 03
N
name of component, upper case
MONDAY,
TUESDAY
n
name of component, lower case
monday, tuesday
Nn
name of component, title case
Monday, Tuesday
1) N, n, and Nn modifiers only support the component M (month).
Examples:
Date String
Picture String
Result
21-03-2002 16:21:12.492
GMT+02:00
[D]-[M]-[Y]
[H]:[m]:[s].[f] [z]
2002-03-21T16:21:12.492+02:00
315 2004 +01:00
[d] [Y] [Z]
2004-11-10T00:00:00+01:00
1.December.10 03:2:39 p.m.
+01:00
[D].[MNn].[Y,2-2]
[h]:[m]:[s] [P] [Z]
2010-12-01T15:02:39+01:00
Example in MapForce:
© 2011 Altova GmbH
Altova MapForce 2011
290
Libraries and Functions
Functions Reference
Result:
parse-number
Available for Java, C#, C++, and the Built-in execution engine.
Converts an input string into a decimal number.
Argument
Description
value
The string to be parsed/converted to a number
format
A format string that identifies the way in which the
number is currently formatted (optional). Default is
"#,##0.#"
decimal-point-charact
er
The character to be used as the decimal point
character. Default is the '.' character (optional)
grouping-separator
The separator/delimiter used to separate groups of
numbers. Default is the "," character (optional)
The format string used in parse-number is the same as that used in format-number.
Example in MapForce:
Result:
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Functions Reference
291
parse-time
Available for Java, C#, C++, and the Built-in execution engine.
Converts a string into an time, while ignoring the date component.
string
Converts an input value into a string. The function can also be used to retrieve the text content
of a node.
If the input node is a XML complex type, then all descendents are also output as a single string.
Comparing differing input node types
If the input nodes are of differing types, e. g. integer and string, you can use the conversion
functions to force a string or numeric comparison.
In the example above the first constant is of type string and contains the string "4".
The second constant contains the numeric constant 12. To be able to compare the two values
explicitly the types must agree.
Adding a number function to the first constant converts the string constant to the numeric value
of 4. The result of the comparisons is then "true".
Note that if the number function were not be used, i.e 4 would be connected directly to the a
parameter, a string compare would occur, with the result being false.
file path functions
The file path functions allow you to directly access and manipulate file path data, i.e. folders, file
names, and extensions for further processing in your mappings. They can be used in all
languages supported by MapForce.
get-fileext
Returns the extension of the file path including the dot "." character.
E.g. 'c:\data\Sample.mfd' returns '.mfd'
© 2011 Altova GmbH
Altova MapForce 2011
292
Libraries and Functions
Functions Reference
get-folder
Returns the folder name of the file path including the trailing slash, or backslash character.
E.g. 'c:/data/Sample.mfd' returns 'c:/data/'
main-mfd-filepath
Returns the full path of the mfd file containing the main mapping. An empty string is returned if
the mfd is currently unsaved.
mfd-filepath
If the function is called in the main mapping, it returns the same as main-mfd-filepath function, i.
e. the full path of the mfd file containing the main mapping. An empty string is returned if the
mfd is currently unsaved.
If called within an user-defined function which is imported by a mfd-file, it returns the full path
of the imported mfd file which contains the definition of the user-defined function.
remove-fileext
Removes the extension of the file path including the dot-character.
E.g. 'c:/data/Sample.mfd' returns 'c:/data/Sample'.
remove-folder
Removes the directory of the file path including the trailing slash, or backslash character.
E.g. 'c:/data/Sample.mfd' returns 'Sample.mfd'.
replace-fileext
Replaces the extension of the file path supplied by the filepath parameter, with the one supplied
by the connection to the extension parameter.
E.g. c:/data/Sample.mfd' as the input filepath, and '.mfp' as the extension, returns 'c:/data/
Sample.mfp'
resolve-filepath
Resolves a relative file path to a relative, or absolute, base folder. The function supports
'.' (current directory) and '..' (parent directory).
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Functions Reference
293
Please see the mapping MergeMultipleFiles_List.mfd available in the ...\MapForceExamples
folder, for an example.
generator functions
The auto-number function generates integers in target nodes of a component, depending on
the various parameters you define.
Make sure that the result connector (of the auto-number function) is directly connnected to a
target node. The exact order in which functions are called by the generated mapping code is
undefined. MapForce may choose to cache calculated results for reuse, or evaluate
expressions in any order. It is therefore strongly recommended to take care when using the
auto-number function.
auto-number
Result is a value starting at start_with and increased by increment. Default values are:
start-with=1 and increase=1. Both parameters can be negative.
global-id
© 2011 Altova GmbH
Altova MapForce 2011
294
Libraries and Functions
Functions Reference
This parameter allows you to synchronize the number sequence output of two separate
auto-number functions connected to a single target component.
If the two auto-number functions do not have the same global-id, then each increments the
target items separately. In the example below, each function has a different global-id i.e. a and
b.
The output of the mapping is 1,1,2,2. The top function supplies the first 1 and the lower one the
second 1.
If both functions have identical global-ids, a in this case, then each function "knows" about the
current auto-number state (or actual value) of the other, and both numbers are then
synchronised/in sequence.
The output of the mapping is therefore 1, 2, 3, 4.The top function supplies the first 1 and the
lower one now supplies a 2.
start-with
The inital value used to start the auto numbering sequence. Default is 1.
increment
The increment you want auto-number sequence to increase by. Default is 1.
restart on change
Resets the auto-number counter to "start-with", when the content of the connected item
changes.
In the example below, start-with and increment are both using the default 1. As soon as the
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Functions Reference
295
content of Department changes, i.e. the department name changes, the counter is reset and
starts at 1 for each new department.
logical functions
Logical functions are (generally) used to compare input data with the result being a boolean
"true" or " false". They are generally used to test data before passing on a subset to the target
component using a filter.
When comparing input parameters, MapForce selects the most specific common type for each
parameter and then compares them. If the common type is anySimpleType, then both input
parameters are compared as strings.
input parameters = a | b, or value1 | value2
output parameter = result
equal
Result is true if a=b, else false.
equal-or-greater
Result is true if a is equal/greater than b, else false.
© 2011 Altova GmbH
Altova MapForce 2011
296
Libraries and Functions
Functions Reference
equal-or-less
Result is true if a is equal/less than b, else false.
greater
Result is true if a is greater than b, else false.
less
Result is true if a is less than b, else false.
logical-and
If both value1 and value2 of the logical-and function are true, then result is true; if different then
false.
logical-not
Inverts or flips the logical state/result; if input is true, result of logical-not function is false. If input
is false then result is true.
The logical-not function shown below, inverts the result of the equal function. The logical-and
function now only returns true if boolean values of value1 and value2 are different, i.e. truefalse, or false-true.
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Functions Reference
297
logical-or
Requires both input values to be boolean. If either value1 or value2 of the logical-or function
are true, then the result is true. If both values are false, then result is false.
not equal
Result is true if a is not equal to b.
math functions
Math functions are used to perform basic mathematical functions on data. Note that they cannot
be used to perform computations on durations, or datetimes.
input parameters = value1 | value2
output parameter = result
input values are automatically converted to decimal for further processing.
The example shown above, adds 20% sales tax to each of the articles mapped to the target
component.
© 2011 Altova GmbH
Altova MapForce 2011
298
Libraries and Functions
Functions Reference
add
Result is the decimal value of adding value1 to value2.
ceiling
Result is the smallest integer that is greater than or equal to value, i.e. the next highest integer
value of the decimal input value.
E.g. if the result of a division function is 11.2, then applying the ceiling function to it makes the
result 12, i.e. the next highest whole number.
divide
Result is the decimal value of dividing value1 by value2. The result precision depends on the
target language. Use the round-precision function to define the precision of result.
floor
Result is the largest integer that is less than or equal to value, i.e. the next lowest integer value
of the decimal input value.
E.g. if the result of a division function is 11.2, then applying the floor function to it makes the
result 11, i.e. the next lowest whole number.
modulus
Result is the remainder of dividing value1 by value2.
In the mapping below, the numbers have been multiplied by 3 and passed on to value1 of the
modulus function. Input values are now 3, 6, 9, and 12.
When applying/using modulus 8 as value2, the remainders are 3, 6, 1, and 4.
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Functions Reference
299
multiply
Result is the decimal value of multiplying value1 by value2.
round
Result is the rounding by half, of value to the nearest integer.
round-precision
Result is the decimal value of the number rounded to the decimal places defined by "decimals".
In the mapping above the result = 0.429.
If you want this result to appear correctly in an XML file, make sure to map to an element of xs:
decimal type.
subtract
Result is the decimal value of subtracting value2 from value1.
node functions
The node testing functions allow you to test for the existence/non-existence of nodes in many
types of input files, XML schema, text, database, EDI and even function results. Exists actually
checks for a non-empty sequence i.e. if any node exists.
exists
Returns true if the node exists, else returns false.
Please see exists for an example.
© 2011 Altova GmbH
Altova MapForce 2011
300
Libraries and Functions
Functions Reference
is-xsi-nil
Returns true (<OrderID>true</OrderID>) if the element node, of the source componenent, has
the xsi:nil attribute set to "true".
node-name
Returns the QName of the connected node unless it is an XML text() node; if this is the case, an
empty QName is returned. This function only works on those nodes that have a name. If XSLT
is the target language (which calls fn:node-name), it returns an empty sequence for nodes
which have no names.
·
·
·
Getting a name from database tables/fields is not supported.
XBRL and Excel are not supported.
Getting a name of File input node is not supported.
·
WebService nodes behave like XML nodes except that:
· node name from "part" is not supported.
· node-name from root node ("Output" or "Input") is not supported.
The MapPerson user-defined function uses node-name to return the name of the input node,
and place it in the role attribute. The root node of the Employees.xsd, in the user-defined
function, has been defined as "Manager".
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Functions Reference
301
Manager gets its data from outside the user-defined function, where it can be either: Manager,
Programmer, or Support. This is the data that is then passed on to the role attribute in
PersonList.
static-node-name
Returns the string with the name of the connected node. The input must be: (i) a source
component node, or (ii) an inline function that is directly connected to a parameter, which in turn
is directly connected to a node in the calling mapping.
The connection must be direct. It cannot pass through a filter or a non-inlined user-defined
function. This is a pseudo-function, which is replaced at generation time with the text acquired
from the connected node, and is therefore available for all languages.
static-node-annotation
Returns the string with annotation of the connected node. The input must be: (i) a source
component node, or (ii) an inline function that is directly connected to a parameter, which in turn
is directly connected to a node in the calling mapping.
The connection must be direct. It cannot pass through a filter or a non-inlined user-defined
function. This is a pseudo-function, which is replaced at generation time with the text acquired
from the connected node, and is therefore available for all languages.
not-exists
Returns false if the node exists, else returns true.
Please see not-exists for an example.
position
Returns the position of a node inside its containing sequence.
Please see position for an example.
set-xsi-nil
Sets the target node to xsi:nil.
© 2011 Altova GmbH
Altova MapForce 2011
302
Libraries and Functions
Functions Reference
subsitute-missing
This function is a convenient combination of exists and a suitable if-else condition. Used to map
the current field content if the node exists in the XML source file, otherwise use the item
mapped to the "replace-with" parameter.
Please see substitute-missing for an example.
substitute-missing-with-xsi-nil
Substitutes any missing (or null values) of the source component, with the xsi:nil attribute in the
target node.
sequence functions
Sequence functions are not available if XSLT (XSLT 1.0) has been selected.
MapForce supports sequence functions which allow the processing of input sequences and the
grouping of their content. The value/content of the key input parameter, mapped to nodes/rows,
is used to group the sequence.
·
Input parameter key is of an arbitrary data type that can be converted to string for
group-adjacent and group-by
·
Input parameter bool is of type Boolean for group-starting-with and group-endingwith
·
The output key is the key of the current group.
distinct-values
Allows you to remove duplicate values from a sequence and map the unique items to the target
component.
Please see distinct-values for an example.
group-adjacent
Groups the input sequence nodes/rows into groups of adjacent items sharing the same key.
Note that group-adjacent uses the content of the node/item as the grouping key!
Please see group-adjacent for an example.
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Functions Reference
303
group-by
Groups the input sequence nodes/rows into groups of not neccessarily adjacent items sharing
the same key. Goups are output in the order the key occurs in the input sequence.
Please see group-by for an example.
group-ending-with
This function groups the input sequence nodes/rows into groups, ending a new group
whenever bool is true.
Please see group-ending-with for an example.
group-starting-with
This function groups the input sequence nodes/rows into groups, starting a new group
whenever bool is true.
Please see group-starting-with for an example.
set-empty
Allows you to cancelof an XBRL document that were defined higher up the XBRL component/
taxonomy.
string functions
The string functions allow you to use the most common string functions to manipulate many
types of source data to: extract portions, test for substrings, or retrieve information on strings.
char-from-code
Result is the character representation of the decimal Unicode value of value.
code-from-char
Result is the decimal Unicode value of the first character of value.
© 2011 Altova GmbH
Altova MapForce 2011
304
Libraries and Functions
Functions Reference
concat
Concatenates (appends) two or more values into a single result string. All input values are auto
matically converted to type string.
contains
Result is true if data supplied to the value parameter contains the string supplied by the
substring parameter.
normalize-space
Result is the normalized input string, i.e. leading and trailing spaces are stripped out, and
multiple consecutive whitespace characters are condensed into a single whitespace character.
starts-with
Result is true if the input string "string" starts with substr, else false.
string-length
Result is the number of characters supplied by the string parameter.
substring
Result is the substring (string fragment) of the "string" parameter where "start" defines the
position of the start character, and "length" the length of the substring.
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Functions Reference
305
If the length parameter is not specified, the result is a fragment starting at the start position and
ending at the end position of the string. Indices start counting at 1.
E.g. substring("56789",2,3) results in 678.
substring-after
Result is the remainder of the "string" parameter, where the first occurrence of the substr
parameter defines the start characters; the remainder of the string is the result of the function.
An empty string is the result, if substr does not occur in string.
E.g. substring-after("2009/01/04","/") results in the substring 01/04. substr in this case is the first
"/"character.
substring-before
Result is the string fragment of the "string" parameter, up to the first occurrence of the substr
characters. An empty string is the result, if substr does not occur in string.
E.g. substring-before ("2009/01/04","/") results in the substring 2009. substr in this case is the
first "/" character.
tokenize
Result is the input string split into a sequence of chunks/sections defined by the delimiter
parameter. The result can then be passed on for further processing.
E.g. Input string is A,B,C and delimiter is "," - then result is A B C.
Please see Tokenize examples for a specific example supplied with MapForce.
tokenize-by-length
Result is the input string split into a sequence of chunks/sections defined by the length
parameter. The result can then be passed on for further processing.
E.g. Input string is ABCDEF and length is "2" - then result is AB CD EF.
Please see Tokenize examples for a specific example supplied with MapForce.
© 2011 Altova GmbH
Altova MapForce 2011
306
Libraries and Functions
Functions Reference
tokenize-regexp
Result is the input string split into a sequence of strings, where the supplied regular expression
pattern match defines the separator. The separator strings are not output by the result
parameter. Optional flags may also be used.
In the example shown above:
input string is a succession of characters separated by spaces and/or commas, i.e. a , b c,d
The regex pattern defines a character class ["space""comma"] - of which one and only one
character will be matched in a character class, i.e. either space or comma.
The + quantifier specifies "one or more" occurrences of the character class/string.
result string is:
Please note that there are slight differences in regular expression syntax between the various
languages. Tokenize-regexp in C++ is only available in Visual Studio 2008 SP1 and later.
For more information on regular expressions please see: Regular expressions.
translate
The characters of string1 (search string) are replaced by the characters at the same position
in string2 (replace string), in the input string "value".
When there are no corresponding characters in string2, the character is removed.
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Functions Reference
307
E.g.
input string is 123145
(search) string1 is 15
(replace) string2 is xy
So:
each 1 is replaced by x in the input string value
each 5 is replaced by y in the input sting value
Result string is x23x4y
If string2 is empty (fewer characters than string1) then the character is removed.
E.g.2
input string aabaacbca
string1 is "a"
string2 is ""
(empty string)
result string is "bcbc"
E.g.3
input string aabaacbca
string1 is "ac"
string2 is "ca"
result string is "ccbccabac"
Tokenize examples
Example tokenize
The tokenizeString1.mfd file available in the ...\MapForceExamples folder shows how the
tokenize function is used.
The XML source file is shown below. The Tool element has two attributes: Name and Code,
with the Tool element data consisting of comma delimited text.
© 2011 Altova GmbH
Altova MapForce 2011
308
Libraries and Functions
Functions Reference
What the mapping does:
· The tokenize function receives data from the Tool element/item and uses the comma ",
" delimiter to split that data into separate chunks. I.e. the first chunk "XML editor".
· As the result parameter is mapped to the Rows item in the target component, one row
is generated for each chunk.
· The result parameter is also mapped to the left-trim function which removes the
leading white space of each chunk.
· The result of the left-trim parameter (each chunk) is mapped to the Feature item of the
target component.
· The target component output file has been defined as a CSV file (AltovaToolFeatures.
csv) with the field delimiter being a semicolon (double click component to see settings).
Result of the mapping:
· For each Tool element of the source file
· The (Tool) Name is mapped to the Tool item in the target component
· Each chunk of the tokenized Tool content is appended to the (Tool Name) Feature
item
· E.g. The first tool, XMLSpy, gets the first Feature chunk "XML editor"
· This is repeated for all chunks of the current Tool and then for all Tools.
· Clicking the Output tab delivers the result shown below.
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Functions Reference
309
Example tokenize-by-length
The tokenizeString2.mfd file available in the ...\MapForceExamples folder shows how the
tokenize-by-length function is used.
The XML source file is shown below, and is the same as the one used in the previous example.
The MissionKit element also has two attributes: Edition and ToolCodes, but no MissionKit
element content.
Aim of the mapping:
To generate a list showing which Altova tools are part of the respective MissionKit editions.
How the mapping works:
· The SelectMissionKit Input component receives its default input from a constant
component, in this case "Enterprise XML Developers".
· The equal function compares the input value with the "Edition" value and passes on
the result to the bool parameter of the ToolCodes filter.
© 2011 Altova GmbH
Altova MapForce 2011
310
Libraries and Functions
·
·
Functions Reference
The node/row input of the ToolCodes filter is supplied by the ToolCodes item of the
source file. The value for the Enterprise XML Developers edition is: XSMFSVDDSASW.
The XSMFSVDDSASW value is passed to the on-true parameter, and futher to the
input parameter of the tokenize-by-length function.
What the tokenize-by-length function does:
· The ToolCodes input value XSMFSVDDSASW, is split into multiple chunks of two
characters each, defined by length parameter, which is 2, thus giving 6 chunks.
· Each chunk (placed in the b parameter) of the equal function, is compared to the 2
character Code value of the source file (of which there are 9 entries/items in total).
· The result of the comparison (true/false) is passed on to the bool parameter of the
filter.
· Note that all chunks, of the tokenize-by-length function, are passed on to the node/row
parameter of the filter.
·
The exists functions now checks for existing/non-existing nodes passed on to it by the
on-true parameter of the filter function.
Existing nodes are those where there is a match between the ToolCodes chunk and
the Code value.
Non-existing nodes are where there was no ToolCodes chunk to match a Code value.
·
The bool results of the exists function are passed on to the if-else function which
passes on a Y to the target if the node exists, or a N, if the node does not exist.
Result of the mapping:
Regular expressions
MapForce can use regular expressions in the pattern parameter of the the match-pattern and
tokenize-regexp functions, to find specific strings of the input parameter.
The regular expression syntax and semantics for XSLT and XQuery are identical to those
defined in http://www.w3.org/TR/xmlschema-2/. Please note that there are slight differences in
regular expression syntax between the various programming languages.
Terminology:
input
the string that the regex works on
pattern the regular expression
flags
optional parameter to define how the regular expression is to be
interpreted
result
the result of the function
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Functions Reference
311
Tokenize-regexp returns a sequence of strings. The connection to the Rows item creates one
row per item in the sequence.
regex syntax
Literals e.g. a single character:
e.g. The letter "a" is the most basic regex. It matches the first occurrence of the character "a" in
the string.
Character classes []
This is a set of characters enclosed in square brackets.
One, and only one, of the characters in the square brackets are matched.
pattern [aeiou]
Matches a lowercase vowel.
pattern [mj]ust
Matches must or just
Please note that "pattern" is case sensitive, a lower case a does not match the uppercase A.
Character ranges [a-z]
Creates a range between the two characters. Only one of the characters will be matched at one
time.
pattern [a-z]
Matches any lowercase characters between a and z.
negated classes [^]
using the caret as the first character after the opening bracket, negates the character class.
pattern [^a-z]
Matches any character not in the character class, including newlines.
Meta characters "."
Dot meta character
matches any single character (except for newline)
pattern .
Matches any single character.
Quantifiers ? + * {}
Quantifiers define how often a regex component must repeat within the input string, for a match
to occur.
© 2011 Altova GmbH
Altova MapForce 2011
312
Libraries and Functions
Functions Reference
?
zero or one
preceding string/chunk is optional
+
one or more
preceding string/chunks may match one or more times
*
zero or more
preceding string/chunks may match zero or more times
{}
min / max
repetitions
no. of repetitions a string/chunks has to match
e.g. mo{1,3} matches mo, moo, mooo.
()
subpatterns
parentheses are used to group parts of a regex together.
|
Alternation/or allows the testing of subexpressions form left to right.
(horse|make) sense - will match "horse sense" or "make sense"
flags
These are optional parameters that define how the regular expression is to be interpreted.
Individual letters are used to set the options, i.e. the character is present. Letters may be in any
order and can be repeated.
s
If present, the matching process will operate in the "dot-all" mode.
The meta character "." matches any character whatsoever. If the input string contains "hello"
and "world" on two different lines, the regular expression "hello*world" will only match if the s
flag/character is set.
m
If present, the matching process operates in multi-line mode.
In multi-line mode the caret ^ matches the start of any line, i.e. the start of the entire string and
the first character after a newline character.
The dollar character $ matches the end of any line, i.e. the end of the entire string and the
character immediately before a newline character.
Newline is the character #x0A.
i
If present, the matching process operates in case-insensitve mode.
The regular expression [a-z] plus the i flag would then match all letters a-z and A-Z.
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Functions Reference
313
x
If present, whitespace characters are removed from the input string prior to the matching
process. Whitespace chars. are #x09, #x0A, #x0D and #x20.
Exception:
Whitespace characters within character class expressions are not removed e.g. [#x20].
Please note:
When generating code, the advanced features of the regex syntax might differ slightly between
the various languages, please see the specific regex documentation for your language.
© 2011 Altova GmbH
Altova MapForce 2011
314
Libraries and Functions
Functions Reference
17.3.2 xpath2
XPath2 functions are available when either XSLT2 or XQuery langauges are selected.
·
·
·
·
·
·
·
·
·
·
accessor functions
anyURIfunctions
boolean functions
constructors
context functions
durations, date and time functions
node functions
numeric functions
QName functions
string functions
accessors
The following accessor functions are available:
base-uri
The base-uri function takes a node argument as input, and returns the URI of the XML
resource containing the node. The output is of type xs:string. MapForce returns an error if no
input node is supplied.
document-uri
Not implemented.
node-name
The node-name function takes a node as its input argument and returns its QName. When the
QName is represented as a string, it takes the form of prefix:localname if the node has a
prefix, or localname if the node has no prefix. To obtain the namespace URI of a node, use the
namespace-URI-from-QName function (in the library of QName-related functions).
string
The string function works like the xs:string constructor: it converts its argument to xs:
string.
When the input argument is a value of an atomic type (for example xs:decimal), this atomic
value is converted to a value of xs:string type. If the input argument is a node, the string value
of the node is extracted. (The string value of a node is a concatenation of the values of the
node's descendant nodes.)
anyURI functions
The resolve-uri function takes a URI as its first argument (datatype xs:string) and resolves
it against the URI in the second argument (datatype xs:string).
The result (datatype xs:string) is a combined URI. In this way a relative URI (the first
argument) can be converted to an absolute URI by resolving it against a base URI.
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Functions Reference
315
In the screenshot above, the first argument provides the relative URI, the second argument the
base URI. The resolved URI will be a concatenation of base URI and relative URI, so C:
\PathtoMyFile\MyFile.xml.
Note:
Both arguments are of datatype xs:string and the process of combining is done by
treating both inputs as strings. So there is no way of checking whether the resources
identified by these URIs actually exist. MapForce returns an error if teh second
argument is not supplied.
boolean functions
The Boolean functions true and false take no argument and return the boolean constant
values, true and false, respectively. They can be used where a constant boolean value is
required.
true
Inserts the boolean value "true".
false
Inserts the boolean value "false".
constructors
The functions in the Constructors part of the XPath 2.0 functions library construct specific
datatypes from the input text. Typically, the lexical format of the input text must be that expected
of the datatype to be constructed. Otherwise, the transformation will not be successful.
For example, if you wish to construct an xs:date datatype, use the xs:date constructor
function. The input text must have the lexical format of the xs:date datatype, which is: YYYYMM-DD (screenshot below).
In the screenshot above, a string constant (2009-08-22) has been used to provide the input
© 2011 Altova GmbH
Altova MapForce 2011
316
Libraries and Functions
Functions Reference
argument of the function. The input could also have been obtained from a node in the source
document.
The xs:date function returns the input text (2009-08-22), which is of xs:string datatype
(specified in the Constant component), as output of xs:date datatype.
When you mouseover the input argument in a function box, the expected datatype of the
argument is displayed in a popup.
context functions
The Context functions library contains functions that provide the current date and time, the
default collation used by the processor, and the size of the current sequence and the position of
the current node.
Date-time functions
The current-date, current-time, and current-dateTime functions take no argument and
return the current date and/or time from the system clock.
The datatype of the result depends on the particular function: current-date returns xs:date,
current-time returns xs:time, and current-dateTime returns xs:dateTime.
default-collation
The default-collation function takes no argument and returns the default collation, that is, the
collation that is used when no collation is specified for a function where one can be specified.
The Altova XSLT 2.0 Engine supports the Unicode codepoint collation only. Comparisons,
including for the fn:max and fn:min functions, are based on this collation.
last, position
The last and position functions take no argument. The last function returns the position of
the last node in the context nodeset. The position function returns the position of the current
node in the nodeset being processed.
The context nodeset at the nodes where the functions are directed, is the nodeset to which the
functions will apply. In the screenshot below, the nodeset of Language elements is the context
nodeset for the last and position functions.
In the example above, the last function returns the position of the last node of the context
nodeset (the nodeset of Language elements) as the value of the number attribute. This value is
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Functions Reference
317
also the size of the nodeset since it indicates the number of nodes in the nodeset.
The position function returns the position of the Language node being currently processed.
For each Language element node, its position within the nodeset of Langauge elements is
output to the language/@position attribute node.
We would advise you to use the position and count functions from the core library.
durations, date and time functions
The duration and date and time functions enable you to adjust dates and times for the
timezone, extract particular components from date-time data, and subtract one date-time unit
from another.
The 'Adjust-to-Timezone' functions
Each of these related functions takes a date, time, or dateTime as the first argument and
adjusts the input by adding, removing, or modifying the timezone component depending on the
value of the second argument.
The following situations are possible when the first argument contains no timezone (for
example, the date 2009-01 or the time 14:00:00).
·
·
·
Timezone argument (the second argument of the function) is present: The result will
contain the timezone specified in the second argument. The timezone in the second
argument is added.
Timezone argument (the second argument of the function) is absent: The result will
contain the implicit timezone, which is the system's timezone. The system's timezone is
added.
Timezone argument (the second argument of the function) is empty: The result will
contain no timezone.
The following situations are possible when the first argument contains a timezone (for example,
the date 2009-01-01+01:00 or the time 14:00:00+01:00).
·
·
·
Timezone argument (the second argument of the function) is present: The result will
contain the timezone specified in the second argument. The original timezone is
replaced by the timezone in the second argument.
Timezone argument (the second argument of the function) is absent: The result will
contain the implicit timezone, which is the system's timezone. The original timezone is
replaced by the system's timezone.
Timezone argument (the second argument of the function) is empty: The result will
contain no timezone.
The 'From' functions
Each of the 'From' functions extracts a particular component from: (i) date or time data, and (ii)
duration data. The results are of the xs:decimal datatype.
As an example of extracting a component from date or time data, consider the day-from-date
function (screenshot below).
© 2011 Altova GmbH
Altova MapForce 2011
318
Libraries and Functions
Functions Reference
The input argument is a date (2009-01-01) of type xs:date. The day-from-date function
extracts the day component of the date (1) as an xs:decimal datatype.
Extraction of time components from durations requires that the duration be specified either as
xs:yearMonthDuration (for extracting years and months) or xs:dayTimeDuration (for
extracting days, hours, minutes, and seconds). The result will be of type xs:decimal. The
screenshot below shows a dayTimeDuration of P2DT0H being input to the days-fromduration function. The result is the xs:decimal 2.
The 'Subtract' functions
Each of the three subtraction functions enables you to subtract one time value from another and
return a duration value. The three subtraction funstions are: subtract-dates, subtract-times
, subtract-dateTimes.
The screenshot below shows how the subtract-dates function is used to subtract two dates (
2009-10-22 minus 2009-09-22). The result is the dayTimeDuration P30D.
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Note:
Functions Reference
319
When you mouseover the input argument in a function box, the expected datatype of
the argument is displayed in a popup.
node functions
The following Node functions are available:
lang
The lang function takes a string argument that identifies a language code (such as en). The
function returns true or false depending on whether the context node has an xml:lang
attribute with a value that matches the argument of the function.
In the screenshot above notice the following:
1. In the source schema, the Language element has an xml:lang attribute.
2. Language nodes are filtered so that only those Language nodes having an xml:lang
value of en are processed (the filter test is specified in the equal function).
3. The Language node is the context node at the point where the en element is created in
the output document.
4. The output of the lang function (true or false) is sent to the en/@exists attribute
node of the output. The argument of the function is provided by the string constant en.
The lang function then checks whether the context node at this point (the Language
element) has an xml:lang attribute with a value of en (the argument of the function). If
yes, then true is returned, otherwise false.
local-name, name, namespace-uri
The local-name, name, and namespace-uri functions, return, respectively, the local-name,
name, and namespace URI of the input node. For example, for the node altova:Products, the
local-name is Products, the name is altova:Products, and the namespace URI is the URI of
the namespace to which the altova: prefix is bound (say, http://www.altova.com/examples
).
Each of these three functions has two variants:
·
·
With no argument: the function is then applied to the context node (for an example of a
context node, see the example given for the lang function above).
An argument that must be a node: the function is applied to the submitted node.
The output of each of these six variants is a string.
© 2011 Altova GmbH
Altova MapForce 2011
320
Libraries and Functions
Functions Reference
number
Converts an input string into a number. Also converts a boolean input to a number.
The number function takes a node as input, atomizes the node (that is, extracts its contents),
and converts the value to a decimal and returns the converted value. The only types that can be
converted to numbers are booleans, strings, and other numeric types. Non-numeric input values
(such as a non-numeric string) result in NaN (Not a Number).
There are two variants of the number function:
·
·
With no argument: the function is then applied to the context node (for an example of a
context node, see the example given for the lang function above).
An argument that must be a node: the function is applied to the submitted node.
numeric functions
The following numeric functions are available:
abs
The abs function takes a numeric value as input and returns its absolute value as a decimal.
For example, if the input argument is -2 or +2, the function returns 2.
round-half-to-even
The round-half-to-even function rounds the supplied number (first argument) to the degree
of precision (number of decimal places) supplied in the optional second argument. For example,
if the first argument is 2.141567 and the second argument is 3, then the first argument (the
number) is rounded to three decimal places, so the result will be 2.141. If no precision (second
argument) is supplied, the number is rounded to zero decimal places, that is, to an integer.
The 'even' in the name of the function refers to the rounding to an even number when a digit in
the supplied number is midway between two values. For example, round-half-to-even
(3.475, 2) would return 3.48.
qname-related functions
There are two QName-related functions that work similarly: local-name-from-QName and
namespace-uri-from-QName.
Both functions take an expanded QName (in the form of a string) as their input arguments and
output, respectively, the local-name and namespace-uri part of the expanded QName.
The important point to note is that since the input of both functions are strings, a node cannot
be connected directly to the input argument boxes of these functions.
The node should first be supplied to the node-name function, which outputs the expanded
QName. This expanded QName can then be provided as the input to the two functions (see
screenshot below).
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Functions Reference
321
The output of both functions is a string.
string functions
The following string functions are available:
compare
The compare function takes two strings as arguments and compares them for equality and
alphabetically. If String-1 is alphabetically less than String-2 (for example the two string are: A
and B), then the function returns -1. If the two strings are equal (for example, A and A), the
function returns 0. If String-1 is greater than String-2 (for example, B and A), then the function
returns +1.
A variant of this function allows you to choose what collation is to be used to compare the
strings. When no collation is used, the default collation, which is the Unicode codepoint
collation, is used. The Altova Engines support the Unicode codepoint collation only.
ends-with
The ends-with function tests whether String-1 ends with String-2. If yes, the function returns
true, otherwise false.
A variant of this function allows you to choose what collation is to be used to compare the
strings. When no collation is used, the default collation, which is the Unicode codepoint
collation, is used. The Altova Engines support the Unicode codepoint collation only.
escape-uri
The escape-uri function takes a URI as input for the first string argument and applies the URI
escaping conventions of RFC 2396 to the string. The second boolean argument (
escape-reserved) should be set to true() if characters with a reserved meaning in URIs are
to be escaped (for example "+" or "/").
For example:
escape-uri("My A+B.doc", true()) would give My%20A%2B.doc
escape-uri("My A+B.doc", false()) would give My%20A+B.doc
lower-case
The lower-case function takes a string as its argument and converts every upper-case
character in the string to its corresponding lower-case character.
© 2011 Altova GmbH
Altova MapForce 2011
322
Libraries and Functions
Functions Reference
matches
The matches function tests whether a supplied string (the first argument) matches a regular
expression (the second argument). The syntax of regular expressions must be that defined for
the pattern facet of XML Schema. The function returns true if the string matches the regular
expression, false otherwise.
The function takes an optional flags argument. Four flags are defined (i, m, s, x). Multiple flags
can be used: for example, imx. If no flag is used, the default values of all four flags are used.
The meaning of the four flags are as follows:
i
Use case-insensitive mode. The default is case-sensitive.
m
Use multiline mode, in which the input string is considered to have multiple lines, each
separated by a newline character (x0a). The meta characters ^ and $ indicate the
beginning and end of each line. The default is string mode, in which the string starts and
ends with the meta characters ^ and $.
s
Use dot-all mode. The default is not-dot-all mode, in which the meta character "."
matches all characters except the newline character (x0a). In dot-all mode, the dot also
matches the newline character.
x
Ignore whitespace. By default whitespace characters are not ignored.
normalize-unicode
The normalize-unicode function normalizes the input string (the first argument) according to
the rules of the normalization form specified (the second argument). The normalization forms
NFC, NFD, NFKC, and NFKD are supported.
replace
The replace function takes the string supplied in the first argument as input, looks for matches
as specified in a regular expression (the second argument), and replaces the matches with the
string in the third argument.
The rules for matching are as specified for the matches attribute above. The function also takes
an optional flags argument. The flags are as described in the matches function above.
starts-with
The starts-with function tests whether String-1 starts with String-2. If yes, the function
returns true, otherwise false.
A variant of this function allows you to choose what collation is to be used to compare the
strings. When no collation is used, the default collation, which is the Unicode codepoint
collation, is used. The Altova Engines support the Unicode codepoint collation only.
substring-after
The substring-after function returns that part of String-1 (the first argument) that occurs after the
test string, String-2 (the second argument). An optional third argument specifies the collation to
use for the string comparison. When no collation is used, the default collation, which is the
Unicode codepoint collation, is used. The Altova Engines support the Unicode codepoint
collation only.
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Functions Reference
323
substring-before
The substring-before function returns that part of String-1 (the first argument) that occurs before
the test string, String-2 (the second argument). An optional third argument specifies the
collation to use for the string comparison. When no collation is used, the default collation, which
is the Unicode codepoint collation, is used. The Altova Engines support the Unicode codepoint
collation only.
upper-case
The upper-case function takes a string as its argument and converts every lower-case
character in the string to its corresponding upper-case character.
© 2011 Altova GmbH
Altova MapForce 2011
324
Libraries and Functions
Functions Reference
17.3.3 xslt
·
xpath functions
The functions in the XPath Functions library are XPath 1.0 nodeset functions.
·
xslt functions
The functions in the XSLT Functions library are XSLT 1.0 functions.
xpath functions
The functions in the XPath Functions library are XPath 1.0 nodeset functions. Each of these
functions takes a node or nodeset as its context and returns information about that node or
nodeset. These function typically have:
·
·
a context node (in the screenshot below, the context node for the lang function is the
Language element of the source schema).
an input argument (in the screenshot below, the input argument for the lang function is
the string constant en). The last and position functions take no argument.
lang
The lang function takes a string argument that identifies a language code (such as en). The
function returns true or false depending on whether the context node has an xml:lang
attribute with a value that matches the argument of the function. In the screenshot above notice
the following:
1. In the source schema, the Language element has an xml:lang attribute.
2. Language nodes are filtered so that only those Language nodes having an xml:lang
value of en are processed (the filter test is specified in the equal function).
3. The Language node is the context node at the point where the en element is created in
the output document.
4. The output of the lang function (true or false) is sent to the en/@exists attribute
node of the output. The argument of the function is provided by the string constant en.
The lang function then checks whether the context node at this point (the Language
element) has an xml:lang attribute with a value of en (the argument of the function). If
yes, then true is returned, otherwise false.
last, position
The last and position functions take no argument. The last function returns the position of
the last node in the context nodeset. The position function returns the position of the current
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Functions Reference
325
node in the nodeset being processed.
The context nodeset at the nodes where the functions are directed is the nodeset to which the
functions will apply. In the screenshot below, the nodeset of Language elements is the context
nodeset for the last and position functions.
In the example above, the last function returns the position of the last node of the context
nodeset (the nodeset of Language elements) as the value of the number attribute. This value is
also the size of the nodeset since it indicates the number of nodes in the nodeset.
The position function returns the position of the Language node being currently processed.
For each Language element node, its position within the nodeset of Langauge elements is
output to the language/@position attribute node.
name, local-name, namespace-uri
These functions are all used the same way and return, respectively, the name, local-name, and
namespace URI of the input node. The screenshot below shows how these functions are used.
Notice that no context node is specified.
The name function returns the name of the Language node and outputs it to the language/
@elementname attribute. If the argument of any of these functions is a nodeset instead of a
single node, the name (or local-name or namespace URI) of the first node in the nodeset is
returned.
The name function returns the QName of the node; the local-name function returns the localname part of the node's QName. For example, if a node's QName is altova:MyNode, then
MyNode is the local name.
© 2011 Altova GmbH
Altova MapForce 2011
326
Libraries and Functions
Functions Reference
The namespace URI is the URI of the namespace to which the node belongs. For example, the
altova: prefix can be declared to map to a namespace URI in this way: xmlns:
altova="http://www.altova.com/namespaces".
Note:
Additional XPath 1.0 functions can be found in the Core function library.
xslt functions
The functions in the XSLT Functions library are XSLT 1.0 functions, and are described below.
Drag a function into the mapping to use it. When you mouseover the input argument part of a
function box, the expected datatype of the argument is displayed in a popup.
current
The current function takes no argument and returns the current node.
document
The document function addresses an external XML document (with the uri argument; see
screenshot below). The optional nodeset argument specifies a node, the base URI of which is
used to resolve the URI supplied as the first argument if this URI is relative. The result is output
to a node in the output document.
Note that the uri argument is a string that must be an absolute file path.
element-available
The element-available function tests whether an element, entered as the only string
argument of the function, is supported by the XSLT processor.
The argument string is evaluated as a QName. Therefore, XSLT elements must have an xsl:
prefix and XML Schema elements must have an xs: prefix—since these are the prefixes
declared for these namespaces in the underlying XSLT that will be generated for the mapping.
Altova MapForce 2011
© 2011 Altova GmbH
Libraries and Functions
Functions Reference
327
The function returns a boolean.
function-available
The function-available function is similar to the element-available function and tests
whether the function name supplied as the function's argument is supported by the XSLT
processor.
The input string is evaluated as a QName. The function returns a boolean.
format-number
The format-number takes an integer as its first argument (value) and a format string as its
second argument (format). The third optional argument is a string that names the decimal
format to use. If this argument is not used, then the default decimal format is used.
Decimal formats are defined by the XSLT 1.0 decimal-format element: each decimal format
so defined can be named and the name can be used as the third argument of the formatnumber function. If a decimal format is defined without a name, it is the default decimal format
for the transformation.
The function returns the number formatted as a string.
generate-id
The generate-id function generates a unique string that identifies the first node in the nodeset
identified by the optional input argument.
If no argument is supplied, the ID is generated on the context node. The result can be directed
to any node in the output document.
© 2011 Altova GmbH
Altova MapForce 2011
328
Libraries and Functions
Functions Reference
system-property
The system-property function returns properties of the XSLT processor (the system). Three
sytsem properties, all in the XSLT namespace, are mandatory for XSLT processors. These are
xsl:version, xsl:vendor, and xsl:vendor-url.
The input string is evaluated as a QName and so must have the xsl:prefix, since this is the
prefix associated with the XSLT namespace in the underlying XSLT stylesheet.
unparsed-entity-uri
If you are using a DTD, you can declare an unparsed entity in it. This unparsed entity (for
example an image) will have a URI that locates the unparsed entity.
The input string of the function must match the name of the unparsed entity that has been
declared in the DTD. The function then returns the URI of the unparsed entity, which can then
be directed to a node in the output document, for example, to an href node.
Altova MapForce 2011
© 2011 Altova GmbH
Chapter 18
QName support
330
QName support
18
QName support
QNames (Qualified Names) allow you reference and abbreviate namespace URIs used in XML
and XBRL instance documents. There are two types of QNames; Prefixed or Unprefixed
QNames.
PrefixedName
Prefix ': LocalPart
'
UnPrefixedNam
LocalPart
e
where LocalPart is an Element or Attribute name.
<Doc xmlns:x="http://myCompany.com">
<x:part>
</Doc>
x is the namespace reference to "http://myCompany.com" and <x:part> is therefore a valid
QName, as:
x is the namespace prefix
part is the LocalPart, i.e. the element name.
When mapping from source to target components QName prefixes will be resolved.
MapForce supports the following QName functions in the Lang section of the Libraries pane:
QName
Constructs a QName from a namespace URI and a local part. Use this function to create a
QName in a target component. The uri and localname parameters can be supplied by a
constant function.
QName-as-string
Converts a QName to a string in the form {http://myCompany.com}local.
local-name-from-QName
Extracts the local name from a QName.
This function is extremely useful when mapping XBRL instance documents containing
hypercubes.
Altova MapForce 2011
© 2011 Altova GmbH
QName support
331
What the mapping does is filter out those facts where the local name of the content of the
explicit member (d-g:Vancouver) is equal to "Vancouver". Note that the content of the member
is itself a QName.
All the facts that belong to the dimension GeographicalBreakdown are filtered out and passed to
the target component.
© 2011 Altova GmbH
Altova MapForce 2011
332
QName support
namespace-uri-from-QName
Extracts the namespace URI from a QName.
Altova MapForce 2011
© 2011 Altova GmbH
Chapter 19
User Reference
334
User Reference
19
User Reference
The following section lists all the menus and menu options in MapForce, and supplies a short
description of each.
Altova MapForce 2011
© 2011 Altova GmbH
User Reference
19.1
File
335
File
New
Creates a new mapping document
Open
Opens previously saved mapping (*.mfd) files.
Please note:
Opening a mapping that contains features available in a higher-level MapForce edition
is not possible.
E.g. A mapping containing Web service features in the Professional version, or
database mappings the Basic editions is not possible.
Save
Saves the currently active mapping using the currently active file name.
Save As
Saves the currently active mapping with a different name, or allows you to supply a new name if
this is the first time you save it.
Save All
Saves all currently open mapping files.
Reload
Reloads the currently active mapping file. You are asked if you want to lose your last changes.
Close
Closes the currently active mapping file. You are asked if you want to save the file before it
closes.
Close All
Closes all currently open mapping files. You are asked if you want to save any of the unsaved
mapping files.
Print
Opens the Print dialog box, from where you can printout your mapping as hardcopy.
"Use current", retains the currently defined zoom factor of the mapping. "Use optimal" scales
© 2011 Altova GmbH
Altova MapForce 2011
336
User Reference
File
the mapping to fit the page size. You can also specify the zoom factor numerically. Component
scrollbars are not printed. You can also specify if you want to allow the graphics to be split over
several pages or not.
Print Preview
Opens the same Print dialog box with the same settings as described above.
Print Setup
Open the Print Setup dialog box in which you can define the printer you want to use and the
paper settings.
Validate Mapping
Validating a Mapping validates that all mappings (connectors) are valid and displays any
warnings or errors.
Please see "Validating mappings" for more information.
Mapping settings
The document-specific settings are defined here. They are stored in the *.mfd file.
Mapping Output
Application Name: defines the XSLT1.0/2.0 file name prefix for the generated transformation
files.
File Path Settings
Make paths absolute in generated code
Ensures compatibility of generated code with mapping files (*.mfd) from versions prior to
Version 2010, please see Relative and absolute file paths for more information.
Ensure Windows path convention for file path...
The "Ensure Windows path convention...." check box makes sure that Windows path
conventions are followed. When outputting XSLT2 (and XQuery), the currently processed file
name is internally retrieved using the document-uri function, which returns a path in the form
file:// URI for local files.
When this check box is active, a file:// URI path specification is automatically converted to a
complete Windows file path (e.g. "C:\...") to simplify further processing.
Altova MapForce 2011
© 2011 Altova GmbH
User Reference
File
337
Generate code in selected language
Generates code in the currently selected language of your mapping. The currently selected
language is visible as a highlighted programming language icon in the toolbar: XSLT, XSLT 2.
Generate code in | XSLT (XSLT2)
This command generates the XSLT file(s) needed for the transformation from the source file(s).
Selecting this option opens the Browse for Folder dialog box where you select the location of
the XSLT file.
Note: the name of the generated XSLT file(s) is defined in the Application Name field of the
Mapping Output dialog box. This dialog is opened by selecting File | Mapping Settings menu
option.
Generate documentation
Generates documention of your mapping projects in great detail in various output formats.
Please see Documenting mapping projects for more information.
Recent files
Displays a list of the most recently opened files.
Recent projects
Displays a list of the most recently opened projects.
Exit
Exits the application. You are asked if you want to save any unsaved files.
© 2011 Altova GmbH
Altova MapForce 2011
338
User Reference
19.2
Edit
Edit
Most of the commands in this menu, become active when you view the result of a mapping in
the Output tab, or preview XSLT code in the XSLT tab.
Undo
MapForce has an unlimited number of "Undo" steps that you can use to retrace you mapping
steps.
Redo
The redo command allows you to redo previously undone commands. You can step backward
and forward through the undo history using both these commands.
Find
Allows you to search for specific text in either the XSLT, XSLT2 or Output tab.
Find Next
F3
Searches for the next occurrence of the same search string.
Find Prevous Shift F3
Serches for the previous occurrence of the same search string.
Cut/Copy/Paste/Delete
The standard windows Edit commands, allow you to cut, copy etc., any components or
functions visible in the mapping window.
Select all
Selects all components in the Mapping tab, or the text/code in the XSLT, XSLT2, or Output tab.
Altova MapForce 2011
© 2011 Altova GmbH
User Reference
19.3
Insert
339
Insert
XML Schema / File
Inserts an XML schema file into the mapping tab as data source or target component. You can
select XML files with a schema reference, in this case the referenced schema is automatically
inserted. If you select an XML schema file, you are prompted if you want to include an XML
instance file which supplies the data for the XSLT, XSLT2, , and Output previews. If you select
an XML file without a schema reference, you are prompted if you want to generate a matching
XML schema automatically.
Constant
Inserts a constant which is a function component that supplies fixed data to an input icon. The
data is entered into a dialog box when creating the component. There is only one output icon on
a constant function. You can select the following types of data: String, Number and All other.
Variable
Inserts an Intermediate Variable which is equivalent to a regular (non-inline) user-defined
function. Variables are structural components, without instance files, and are used to simplify
the mapping process. Please see Intermediate variables for more information.
Filter: Nodes/Rows
Inserts a component that uses two input and output parameters: node/row and bool, and
on-true, on-false. If the Boolean is true, then the value of the node/row parameter is forwarded
to the on-true parameter. If the Boolean is false, then the complement value is passed on to the
on-false parameter. Please see the tutorial example on how to use a filter.
Value-Map
Inserts a component that transforms an input value to an output value using a lookup table. The
component only has one input and output item. Please see Value-Map - transforming input data
for more information.
IF-Else Condition
A condition is a component which allows you to pass on different sets of data depending on the
outcome of a preset condition. The component header displays the text if-else.
·
·
·
·
The first input parameter is a bool, which contains the data you are checking against.
The value-true input parameter supplies the data to be passed on, as a result, if the
condition is true.
The value-false supplies the data to be passed on if the condition is false.
The result parameter outputs the data supplied by the value-true/false input
parameters.
The IF-Else function is extendable. This means that you can check for multiple conditions and
© 2011 Altova GmbH
Altova MapForce 2011
340
User Reference
Insert
use the otherwise parameter to output the Else condition/value.
Clicking the "plus" icon inserts or appends a new if-else pair, i.e. boolX and value-trueX, while
clicking the "x" deletes the parameter pair.
In the example above, the temperature data is analyzed:
·
If temp is greater than 20, then true is passed on to bool1 and the result is "high" from
value-true1.
·
Else, If temp is less than 5, then true is passed on to bool2 and the result is "low"
from value-true2.
·
Otherwise, nothing (an empty sequence) is the result of the component, since there is
no connection to the "otherwise" input.
Result of the mapping:
Altova MapForce 2011
© 2011 Altova GmbH
User Reference
19.4
Component
341
Component
Change Root Element
Allows you to change the root element of the XML instance document.
Edit Schema Definition in XMLSpy
Selecting this option, having previously clicked an XML-Schema/document, opens the XML
Schema file in the Schema view of XMLSpy where you can edit it.
Add Duplicate Input Before
Inserts a copy/clone of the selected item before the currently selected item. Duplicate items do
not have output icons, you cannot use them as data sources. Please see the Duplicating input
items section in the tutorial for an example of this.
Right clicking a duplicate item also allows you to reposition it using the menu items Move
Up/Move Down, depending on where the item is.
Add Duplicate Input After
Inserts a copy/clone of the selected item after the currently selected item. Duplicate items do
not have output icons, you cannot use them as data sources. Please see the Duplicating input
items section in the tutorial for an example of this.
Right clicking a duplicate item also allows you to reposition it using the menu items Move
Up/Move Down, depending on where the item is.
Remove Duplicate
Removes a previously defined duplicate item. Please see the Duplicating input items section in
the tutorial for more information.
Align Tree Left
Aligns all the items along the left hand window border.
Align Tree Right
Aligns all the items along the right hand window border. This display is useful when creating
mappings to the target schema.
Properties
Opens a dialog box which displays the currently selected component settings. If the component
is an XML-Schema file then the Component Settings dialog box is opened. If the component is
a Text file, then the "Text import / export" dialog box is opened.
© 2011 Altova GmbH
Altova MapForce 2011
342
User Reference
Component
Schema file: Shows the file name and path of the target schema.
Input XML-File: Allows you to select, or change the XML-Instance for the currently selected
schema component. This field is filled when you first insert the schema component and
assign an XML-instance file.
Output XML-File: This is file name and path where the XML target instance is placed, when
generating and executing program code. The file name is also visible as the first item in
the component.
The entry from the Input XML-Instance field, is automatically copied to this field when
you assign the XML-instance file. If you do not assign an XML-Instance file to the
component, then this field contains the entry schemafilenameandpath.xml.
Altova MapForce 2011
© 2011 Altova GmbH
User Reference
Component
343
Prefix for target namespace: Allows you to enter a prefix for the Target Namespace if this
is a schema / XML document. A Target namespace has to be defined in the target
schema, for the prefix to be assigned here.
Add Schema/DTD reference: Adds the path of the referenced XML Schema file to the root
element of the XML output.
Entering a path in this field allows you to define where the schema file, referenced by
the XML instance file, is to be located. This ensures that the output instance can be
validated at the mapping destination when the mapping is executed. You can enter an
http:// address as well as an absolute or relative path in this field.
Deactivating this option allows you to decouple the XML instance from the referenced
XML Schema or DTD. E.g. if you want to send the resulting XML output to someone
who does not have access to the underlying XML Schema.
Cast target values to target types: Allows you to define if the target XML schema types
should be used when mapping (default - active), or if all data mapped to the target
component should be treated as string values.
Deactivating this option allows you to retain the precise formatting of values. E.g., this is
useful to "satisfy" a pattern facet in a schema, that requires a specific number of
decimal digits in a numeric value.
You can use mapping functions to format the number as a string in the required format,
and then map this string to the target.
Note that disabling this option will also disable the detection of invalid values, e.g.
writing letters into numeric fields.
Pretty-print output: Reformats your XML document in the Output pane to give a structured
display of the document. (Each child node is offset from its parent by a single tab
character.)
Encoding settings
From MapForce version 2008 each component, source, as well as target, has its own encoding
settings. This means that the *.mfd mapping files do not have a default encoding, each
component that makes up the mapping file has its own. Components in this general sense are
all XML, and Text components.
There is however a default encoding setting defined in the Tools | Options General tab, called
"Default encoding for new components" which is applied whenever new components are
created/inserted. When mappings from previous versions are opened, the default encoding
setting will be used.
The encoding control group consists of 3 controls:
·
·
·
Encoding name selection combobox.
Byte order selection combobox (little endian, big endian).
Include Byte Order Mark checkbox.
© 2011 Altova GmbH
Altova MapForce 2011
344
User Reference
Component
Default settings are:
· UTF-8
· little endian (disabled for UTF-8)
· no Byte Order Mark.
Please note:
Activating the Byte Order Mark check box in the Component Settings dialog box, does
not have any effect when outputting XSLT 1.0/2.0, as these languages do not support
BOMs (Byte Order Marks).
Enable input processing optimizations based on min/maxOccurs
MapForce version 2009 introduces special handling for sequences that are known to contain
exactly one item, e.g. required attributes, or child elements with minOccurs and maxOccurs = 1.
In this case the first item of the sequence is extracted, then the item is directly processed as an
atomic value (and not as a sequence).
If the input data is not valid against the schema, an empty sequence might be encountered in a
mapping, which stops the mapping with an error message. To allow the processing of such
invalid input, this optimization can be disabled in the component settings of XML and EDI
components.
Altova MapForce 2011
© 2011 Altova GmbH
User Reference
19.5
Connection
345
Connection
Auto Connect Matching Children
Activates or de-activates the "Auto connect child items" function, as well as the icon in the icon
bar.
Settings for Connect Matching Children
Opens the Connect Matching Children dialog box in which you define the connection settings.
Connect Matching Children
This command allows you to create multiple connectors for items of the same name, in both
the source and target schemas. The settings you define in this dialog box are retained, and are
applied when connecting two items, if the "Auto connect child items" icon
in the title bar is
active. Clicking the icon, switches between an active and inactive state. Please see the section
on Connector properties for further information.
Target Driven (Standard)
Changes the connector type to Standard mapping, please see: "Source-driven / mixed content
vs. standard mapping" for more information.
Copy-all (Copy Child Items)
Creates connectors for all matching child items, where each of the child connectors are
displayed as a subtree of the parent connector, please see "Copy-all connections" for more
information.
Source Driven (Mixed Content)
Changes the connector type to source driven / mixed content, and enables the selection of
additional elements to be mapped. The additional elements have to be child items of the
mapped item in the XML source file, to be able to be mapped. Please see Default settings:
mapping mixed content for more information.
Properties:
Opens a dialog box in which you can define the specific (mixed content) settings of the current
connector. Note that unavailable options are greyed out.
Please note that these settings also apply to complexType items which do not have any text
nodes!
© 2011 Altova GmbH
Altova MapForce 2011
346
User Reference
Connection
Annotation settings:
Individual connectors can be labeled for clarity.
1. Double click a connector and enter the name of the connector in the Description field.
This enables all the options in the Annotation Settings group.
2. Use the remaining groups to define the position and alignment of the label.
Connector context menu:
Connect matching children
Altova MapForce 2011
© 2011 Altova GmbH
User Reference
Connection
347
Opens the "Connect Matching Children" dialog box, allowing you to change the connection
settings and connect the items when confirming with OK.
Delete
Deletes the selected connector.
Target Driven (Standard)
Changes the connector type to Standard mapping, please see: "Source-driven / mixed content
vs. standard mapping" for more information.
Copy-all (Copy Child Items)
Changes the connector type to "Copy-all" and connects all child items of the same name in a
graphically optimized fashion, please see "Copy-all connections" for more information.
Source Driven (Mixed Content)
Changes the connector type to source-driven / mixed content, please see: "Source driven and
mixed content mapping" for more information.
Insert Filter: Nodes/Rows
Inserts a Filter component into the connector. The source connector is connected to the
nodes/row parameter, and the target connector is connected to the on-true parameter. Please
see Filter - retrieving dynamic data, lookup table for more information.
Properties:
Opens the Connections Settings dialog, in which you can define the specific mixed content
settings as well as the connector annotation settings, please see the Connection section in the
Reference section.
Connect Matching Children dialog box
This command allows you to create multiple connectors between items of the same name in
both the source and target components. Note that a copy-all connection is created by default.
1. Connect two (parent) items that share identically named child items in both
components.
2. Right click the connector and select the Connect matching child elements option.
3. Select the required options discussed in the text below, and click OK to create the
© 2011 Altova GmbH
Altova MapForce 2011
348
User Reference
Connection
connectors.
Connectors are created for all the child items that have identical names and adhere to
the settings defined in the dialog box.
Please note:
The settings you define here are retained, and are applied when connecting two items,
if the "Auto connect child items" icon
in the title bar is active. Clicking the icon
switches between an active and inactive state.
Ignore Case:
Ignores the case of the child item names.
Ignore Namespaces:
Ignores the namespaces of the child items.
Recursive:
Having created the first set of connectors, the grandchild items are then checked for identical
names. If some exist, then connectors are also created for them. The child elements of these
items are now checked, and so on.
Mix Attributes and Elements:
Allows the creation of connectors between items of the same name, even if they are of different
types e.g. two "Name" items exist, but one is an element, the other an attribute. If set active, a
connector is created between these items.
Create copy-all connections:
Default setting is active. Creates copy-all connection between source and target items if
possible.
Existing connections:
Ignore existing output connections:
Creates additional connectors to other components, even if the currently existing output icons
already have connectors.
Retain
Retains existing connectors.
Overwrite:
Recreates connectors, according to the settings defined. Existing connectors are scrapped.
Delete all existing:
Deletes all existing connectors, before creating new ones.
Deleting connections
Connectors that have been created using the Connect Matching Children dialog, or during the
mapping process can be removed as a group.
Altova MapForce 2011
© 2011 Altova GmbH
User Reference
Connection
349
Right click the item name in the component, not the connector itself, Person in this example.
Select Delete Connections | Delete all ... connections.
Delete all direct connections:
Deletes all connectors directly mapped to, or from, the current component to any other source
or target components.
Delete all incoming child connections:
Only active if you have right clicked an item in a target component. Deletes all incoming child
connectors.
Delete all outgoing child connections:
Only active if you have right clicked an item in a source component. Deletes all outgoing child
connectors.
© 2011 Altova GmbH
Altova MapForce 2011
350
User Reference
19.6
Function
Function
Create User-Defined Function...:
Creates a new user-defined function. Selecting this option creates and empty user-defined
function, into which you insert the components you need. A single output component is
automatically inserted when you define such a function, and only one output component can be
present in a user-defined function unless it is defined as inlined. Please see "Creating a
user-defined function from scratch" for more information.
Create User-Defined Function from Selection:
Creates a new user-defined function based on the currently selected elements in the mapping
window. Please see "Adding user-defined functions" for more information.
Function Settings:
Opens the settings dialog box of the currently active user-defined function allowing you to
change the current settings. Use this method to change the user-defined function type, i.e.
double click the title bar of a user-defined function to see its contents, then select this menu
option to change its type.
Remove Function
Deletes the currently active user-defined function while working on an existing user-defined
function, in the tab of that name. I.e this only works on existing user-defined functions while
viewing their contents.
A prompt appears reminding you that instances may become invalid and in what libraries the
user-defined function exists.
Insert Input:
Inserts an "input" component into the mapping, or into a user-defined function.
If you are working in the main Mapping tab, the dialog box shown below is displayed. This type
of input component allows you to define a parameter in the command line execution of the
compiled mapping.
Please see "Input values, overrides and command line parameters" for more information.
Altova MapForce 2011
© 2011 Altova GmbH
User Reference
Function
351
If you are working in a user-defined function tab, the dialog box shown below is displayed. This
type of input component allows you to define:
·
·
simple inputs
complex inputs, e.g. schema structures
Insert Output
Inserts an "Output" component into a user-defined function. In a user-defined function tab, the
dialog box shown below is displayed. This type of input component allows you to define:
·
·
simple outputs
complex outputs, e.g. schema structures
© 2011 Altova GmbH
Altova MapForce 2011
352
User Reference
Altova MapForce 2011
Function
© 2011 Altova GmbH
User Reference
19.7
Output
353
Output
The first group of options (XSLT 1.0, XSLT 2.0, etc.) allow you to define the target language
you want your code to be in.
Note that the Built-in execution engine presents a preview of the mapping result, when you click
the Output tab and cannot be used to generate program code. .
Validate Output
Validates the output XML file against the referenced schema.
Save generated Output
Saves the currently visible data in the Output tab.
Save all generated outputs
Saves all the generated output files of dynamic mappings. Please see: Dynamic Input/Output
file name for more information.
Regenerate output
Regenerates the current mapping from the Output windown.
Insert/Remove Bookmark
Inserts a bookmark at the cursor position in the Output window.
Next Bookmark
Navigates to the next bookmark in the Output window.
Previous Bookmark
Navigates to the previous bookmark in the Output window.
Remove All Bookmarks
Removes all currently defined bookmarks in the Output window.
Pretty-Print XML Text
Reformats your XML document in the Output pane to give a structured display of the document.
Each child node is offset from its parent by a single tab character.
Text View Settings
Allows you to customize the text settings in the Output window and also shows the currently
defined hotkeys that apply in the window.
© 2011 Altova GmbH
Altova MapForce 2011
354
User Reference
Altova MapForce 2011
Output
© 2011 Altova GmbH
User Reference
19.8
View
355
View
Show Annotations
Displays XML schema annotations in the component window.
If the Show Types icon is also active, then both sets of info are show in grid form.
Show Types
Displays the schema datatypes for each element or attribute.
If the Show Annotations icon is also active, then both sets of info are show in grid form.
Show library in Function Header
Displays the library name in parenthesis in the function title.
Show Tips
Displays a tooltip containing explanatory text when the mouse pointer is placed over a function.
Show Selected Component Connectors
Switches between showing:
·
·
all mapping connectors, or
those connectors relating to the currently selected components.
Show Connectors from Source to Target
Switches between showing:
·
·
connectors that are directly connected to the currently selected component, or
connectors linked to the currently selected component, originating from source and
terminating at the target components.
Zoom
Opens the Zoom dialog box. You can enter the zoom factor numerically, or drag the slider to
change the zoom factor interactively.
Back
Steps back through the currently open mappings of the mapping tab.
Forward
Steps forward through the currently open mappings of the mapping tab.
Status Bar
Switches the Status Bar, visible below the Messages window, on or off.
Library Window
Switches the Library window, containing all library functions, on or off.
Messages
Switches the Validation output window on, or off. When generating code the Messages output
window is automatically activated to show the validation result.
© 2011 Altova GmbH
Altova MapForce 2011
356
User Reference
View
Overview
Switches the Overview window on, or off. Drag the rectangle to navigate your Mapping view.
Altova MapForce 2011
© 2011 Altova GmbH
User Reference
19.9
Tools
357
Tools
Global Resources
Opens the Manage Global Resources dialog box allowing you to Add, Edit and Delete global
resources to the Global Resources XML file, please see Global Resources - Properties for more
information.
Active Configuration
Allows you to select/change the currently active global resource from a list of all resources/
configurations in the Global Resources. Select the required configuration from the submenu.
Create Reversed Mapping
Creates a "reversed" mapping from the currently active mapping in MapForce, which is to be
the basis of a new mapping. Note that the result is not intended to be a complete mapping, only
the direct connections between components are retained in the reversed mapping. It is very
likely that the resulting mapping will not be valid, or be able to be executed when clicking the
Output tab, without manual editing.
E.g. Tut-ExpReport.mfd in the ...\MapForceExamples\Tutorial folder:
© 2011 Altova GmbH
Altova MapForce 2011
358
User Reference
Tools
Result of a reversed mapping:
General:
· The source component becomes the target component, and target component
becomes the source.
· If an Input, and Output XML, instance file have been assigned to a component, then
they will both be swapped.
Altova MapForce 2011
© 2011 Altova GmbH
User Reference
Tools
359
Retained connections
· Direct connections between components
· Direct connections between components in a chained mapping
· The type of connection: Standard, Mixed content, Copy-All
·
·
Pass-through component settings
Database components are unchanged.
Deleted connections
· Connections via functions, filters etc. are deleted, along with the functions etc.
· User-defined functions
· Webservice components
Restore Toolbars and Windows
Resets the toolbars, entry helper windows, docked windows etc. to their defaults. MapForce
needs to be restarted for the changes to take effect.
Customize...
The customize command lets you customize MapForce to suit your personal needs.
The Keyboard tab allows you to define (or change) keyboard shortcuts for any MapForce
command.
To assign a new Shortcut to a command:
1. Select the Tools | Customize command and click the Keyboard tab.
2. Click the Category combo box to select the menu name.
3. Select the command you want to assign a new shortcut to, in the Commands list box
4. Click in the Press New Shortcut Key: text box, and press the shortcut keys that are to
activate the command.
© 2011 Altova GmbH
Altova MapForce 2011
360
User Reference
Tools
The shortcuts appear immediately in the text box. If the shortcut was assigned
previously, then that function is displayed below the text box.
5. Click the Assign button to assign the shortcut.
The shortcut now appears in the Current Keys list box.
(To clear the entry in the Press New Shrotcut Key text box, press any of the control
keys, CTRL, ALT or SHIFT).
To de-assign or delete a shortcut:
1. Click the shortcut you want to delete in the Current Keys list box.
2. Click the Remove button.
3. Click the Close button to confirm.
Set accelerator for:
Currently no function.
Currently assigned keyboard shortcuts:
Hotkeys by key
F1
F2
F3
F10
Num +
Num Num *
Help Menu
Next bookmark (in output window)
Find Next
Activate menu bar
Expand current item node
Collapse item node
Expand all from current item node
CTRL + TAB
CTRL + F6
CTRL + F4
Switches between open mappings
Cycle through open windows
Closes the active mapping document
Alt + F4
Alt + F, F, 1
Alt + F, T, 1
Closes MapForce
Opens the last file
Opens the last project
CTRL + N
CTRL + O
CTRL + S
CTRL + P
File New
File Open
File Save
File Print
CTRL + A
CTRL + X
CTRL + C
CTRL + V
CTRL + Z
CTRL + Y
Select All
Cut
Copy
Paste
Undo
Redo
Del
Shift + Del
CTRL + F
F3
Shift + F3
Delete component (with prompt)
Delete component (no prompt)
Find
Find Next
Find Previous
Arrow keys
(up / down)
Esc
Return
Select next item of component
Abandon edits/close dialog box
Confirms a selection
Altova MapForce 2011
© 2011 Altova GmbH
User Reference
Tools
Output window hotkeys
CTRL + F2
F2
SHIFT + F2
CTRL + SHIFT + F2
361
Insert Remove/Bookmark
Next Bookmark
Previous Bookmark
Remove All Bookmarks
Zooming hotkeys
CTRL + mouse wheel forward Zoom In
CTRL + mouse wheel back
Zoom Out
CTRL + 0 (Zero)
Reset Zoom
Options
Opens the Options dialog box through which you can:
·
·
Add or delete user defined XSLT functions.
Define general settings, such as the default character encoding for new components, in
the General tab.
General tab:
· Specify if you want to show the logo on start and/or when printing.
· Enable/disable the MapForce gradient background
· Limit the annotation text in components to X lines. Also applies to SELECT statements
visible in a component.
· Define the default character encoding for new components
· an execution timeout for the Output tab when previewing the mapping result.
· specify if you want to output to temporary files (default), or write output files directly to
disk when clicking the Output button/tab.
Warning: Enabling "Write directly to final output files" will overwrite output files without
requesting further confirmation.
·
Allows you to limit the output to X million characters, when outputting to the built-in
execution engine. The Built-in execution engine is the only target that supports XML,
CSV, and FLF streaming
Libraries tab:
· Add or delete user-defined XSLT, or programming language Libraries/functions to
MapForce.
© 2011 Altova GmbH
Altova MapForce 2011
362
User Reference
Window
19.10 Window
Cascade
This command rearranges all open document windows so that they are all cascaded (i.e.
staggered) on top of each other.
Tile Horizontal
This command rearranges all open document windows as horizontal tiles, making them all
visible at the same time.
Tile Vertical
This command rearranges all open document windows as vertical tiles, making them all visible
at the same time.
1
2
This list shows all currently open windows, and lets you quickly switch between them.
You can also use the Ctrl-TAB or CTRL F6 keyboard shortcuts to cycle through the open
windows.
Altova MapForce 2011
© 2011 Altova GmbH
User Reference
Help Menu
363
19.11 Help Menu
The Help menu contains commands to access the onscreen help manual for MapForce,
commands to provide information about MapForce, and links to support pages on the Altova
web site. The Help menu also contains the Registration dialog, which lets you enter your license
key-code once you have purchased the product.
The description of the Help menu commands is organized into the following sub-sections:
·
·
·
Table of Contents, Index, Search
Registration, Order Form
Other Commands
© 2011 Altova GmbH
Altova MapForce 2011
364
User Reference
Help Menu
19.11.1 Table of Contents, Index, Search
The Table of Contents command opens the onscreen help manual for MapForce with the
Table of Contents displayed in the left-hand-side pane of the Help window. The Table of
Contents provides a good overview of the entire Help document. Clicking an entry in the Table
of Contents takes you to that topic.
The Index command opens the onscreen help manual for MapForce with the Keyword Index
displayed in the left-hand-side pane of the Help window. The index lists keywords and lets you
navigate to a topic by double-clicking the keyword. If a keyword is linked to more than one topic,
you are presented with a list of the topics to choose from.
The Search command opens the onscreen help manual for MapForce with the Search dialog
displayed in the left-hand-side pane of the Help window. To search for a term, enter the term in
the input field, and press Return. The Help system performs a full-text search on the entire Help
documentation and returns a list of hits. Double-click any item to display that item.
Altova MapForce 2011
© 2011 Altova GmbH
User Reference
Help Menu
365
19.11.2 Activation, Order Form, Registration, Updates
Software Activation
After you download your Altova product software, you can activate it using either a free
evaluation key or a purchased permanent license key.
·
·
Note:
Free evaluation key. When you first start the software after downloading and installing
it, the Software Activation dialog will pop up. In it is a button to request a free evaluation
key-code. Enter your name, company, and e-mail address in the dialog that appears,
and click Request Now! The evaluation key is sent to the e-mail address you entered
and should reach you in a few minutes. Now enter the key in the key-code field of the
Software Activation dialog box and click OK to start working with your Altova product.
The software will be unlocked for a period of 30 days.
Permanent license key. The Software Activation dialog contains a button to purchase
a permanent license key. Clicking this button takes you to Altova's online shop, where
you can purchase a permanent license key for your product. There are two types of
permanent license: single-user and multi-user. Both will be sent to you by e-mail. A
single-user license contains your license-data and includes your name, company,
e-mail, and key-code.A multi-user license contains your license-data and includes your
company name and key-code. Note that your license agreement does not allow you to
install more than the licensed number of copies of your Altova software on the
computers in your organization (per-seat license). Please make sure that you enter the
data required in the registration dialog exactly as given in your license e-mail.
When you enter your license information in the Software Activation dialog, ensure that
you enter the data exactly as given in your license e-mail. For multi-user licenses, each
user should enter his or her own name in the Name field.
The Software Activation dialog can be accessed at any time by clicking the Help | Software
Activation command.
Order Form
When you are ready to order a licensed version of MapForce, you can use either the Order
license key button in the Software Activation dialog (see previous section) or the Help | Order
Form command to proceed to the secure Altova Online Shop.
Registration
The first time you start your Altova software after having activated it, a dialog appears asking
whether you would like to register your product. There are three buttons in this dialog:
·
·
·
OK: Takes you to the Registration Form
Remind Me Later: Pops up a dialog in which you can select when you wish to be next
reminded.
Cancel: Closes the dialog and suppresses it in future. If you wish to register at a later
time, you can use the Help | Registration command.
Check for Updates
Checks with the Altova server whether a newer version than yours is currently available and
displays a message accordingly
© 2011 Altova GmbH
Altova MapForce 2011
366
User Reference
Help Menu
19.11.3 Other Commands
The Support Center command is a link to the Altova Support Center on the Internet. The
Support Center provides FAQs, discussion forums where problems are discussed, and access
to Altova's technical support staff.
The FAQ on the Web command is a link to Altova's FAQ database on the Internet. The FAQ
database is constantly updated as Altova support staff encounter new issues raised by
customers.
The Components Download command is a link to Altova's Component Download Center on
the Internet. From here you will be able to download a variety of companion software to use with
Altova products. Such software ranges from XSLT and XSL-FO processors to Application
Server Platforms. The software available at the Component Download Center is typically free of
charge.
The MapForce on the Internet command is a link to the Altova website on the Internet. You
can learn more about MapForce and related technologies and products at the Altova website.
The MapForce Training command is a link to the Online Training page at the Altova website.
Here you can select from online courses conducted by Altova's expert trainers.
The About MapForce command displays the splash window and version number of your
product.
Altova MapForce 2011
© 2011 Altova GmbH
Chapter 20
Appendices
368
Appendices
20
Appendices
These appendices contain technical information about MapForce and important licensing
information. Each appendix contains sub-sections as given below:
Technical Data
·
·
·
·
·
·
OS and memory requirements
Altova XML Parser
Altova XSLT and XQuery Engines
Unicode support
Internet usage
License metering
License Information
·
·
·
Electronic software distribution
Copyrights
End User License Agreement
Altova MapForce 2011
© 2011 Altova GmbH
Appendices
20.1
Engine information
369
Engine information
This section contains information about implementation-specific features of the Altova XML
Validator, Altova XSLT 1.0 Engine, Altova XSLT 2.0 Engine, and Altova XQuery Engine.
© 2011 Altova GmbH
Altova MapForce 2011
370
Appendices
Engine information
20.1.1 XSLT 1.0 Engine: Implementation Information
The Altova XSLT 1.0 Engine is built into Altova's XMLSpy, StyleVision, Authentic, and
MapForce XML products. It is also available in the free AltovaXML package. The Altova XSLT
1.0 Engine implements and conforms to the World Wide Web Consortium's XSLT 1.0
Recommendation of 16 November 1999 and XPath 1.0 Recommendation of 16 November 1999
. Limitations and implementation-specific behavior are listed below.
Limitations
·
·
The xsl:preserve-space and xsl:strip-space elements are not supported.
When the method attribute of xsl:output is set to HTML, or if HTML output is
selected by default, then special characters in the XML or XSLT file are inserted in the
HTML document directly as special characters; they are not inserted as HTML
character references in the output. For instance, the character &#160; (the decimal
character reference for a non-breaking space) is not inserted as &nbsp; in the HTML
code, but directly as a non-breaking space.
Implementation's handling of whitespace-only nodes in source XML document
The XML data (and, consequently, the XML Infoset) that is passed to the Altova XSLT 1.0
Engine is stripped of boundary-whitespace-only text nodes. (A boundary-whitespace-only text
node is a whitespace-only text node that occurs between two elements within an element of
mixed content.) This stripping may have an effect on the value returned by the
fn:position(), fn:last(), and fn:count() functions.
For any node selection that selects text nodes also, boundary-whitespace-only text nodes would
typically also be included in the selection. However, since the XML Infoset used by the Altova
engines has boundary-whitespace-only text nodes stripped from it, these nodes are not present
in the XML Infoset. As a result, the size of the selection and the numbering of nodes in the
selection will be different than that for a selection which included these text nodes. The
fn:position(), fn:last(), and fn:count() functions, therefore, could produce results
that are different from those produced by some other processors.
A situation in which boundary-whitespace-only text nodes are evaluated as siblings of other
elements arises most commonly when xsl:apply-templates is used to apply templates.
When the fn:position(), fn:last(), and fn:count() functions are used in patterns with
a name test (for example, para[3], which is short for para[position()=3]),
boundary-whitespace-only nodes are irrelevant since only the named elements (para in the
above example) are selected. (Note, however, that boundary-whitespace-only nodes are
relevant in patterns that use the wildcard, for example, *[10].)
Note: If a boundary-whitespace-only text node is required in the output, then insert the required
whitespace within one of the two adjoining child elements. For example, the XML fragment:
<para>This is <b>bold</b> <i>italic</>.</para>
when processed with the XSLT template
<xsl:template match="para">
<xsl:apply-templates/>
</xsl:template>
will produce:
This is bolditalic.
To get a space between bold and italic in the output, insert a space character within either
Altova MapForce 2011
© 2011 Altova GmbH
Appendices
Engine information
371
the <b> or <i> elements in the XML source. For example:
<para>This is <b>bold</b> <i> italic</i>.</para> or
<para>This is <b>bold&#x20;</b> <i>italic</i>.</para> or
<para>This is <b>bold</b><i>&#x20;italic</i>.</para>
When any of the para elements above is processed with the same XSLT template given
above, it will produce:
This is bold italic.
© 2011 Altova GmbH
Altova MapForce 2011
372
Appendices
Engine information
20.1.2 XSLT 2.0 Engine: Implementation Information
The Altova XSLT 2.0 Engine is built into Altova's XMLSpy, StyleVision, Authentic, and
MapForce XML products. It is also available in the free AltovaXML package. This section
describes the engine's implementation-specific aspects of behavior. It starts with a section
giving general information about the engine, and then goes on to list the implementation-specific
behavior of XSLT 2.0 functions.
For information about implementation-specific behavior of XPath 2.0 functions, see the section,
XPath 2.0 and XQuery 1.0 Functions.
General Information
The Altova XSLT 2.0 Engine conforms to the World Wide Web Consortium's (W3C's) XSLT
2.0 Recommendation of 23 January 2007. Note the following general information about the
engine.
Backwards Compatibility
The Altova XSLT 2.0 Engine is backwards compatible. The only time the backwards
compatibility of the XSLT 2.0 Engine comes into play is when using the XSLT 2.0 Engine of
Altova XML to process an XSLT 1.0 stylesheet. Note that there could be differences in the
outputs produced by the XSLT 1.0 Engine and the backwards-compatible XSLT 2.0 Engine.
In all other Altova products, the backwards-compatibility issue never arises. This is because
these products automatically select the appropriate engine for the transformation. For example,
consider that in XMLSpy you specify that a certain XML document be processed with an XSLT
1.0 stylesheet. When the transformation command is invoked, XMLSpy automatically selects
the XSLT 1.0 Engine of XMLSpy to carry out the transformation.
Note:
The stylesheet version is specified in the version attribute of the stylesheet or
transform element of the stylesheet.
Namespaces
Your XSLT 2.0 stylesheet should declare the following namespaces in order for you to be able
to use the type constructors and functions available in XSLT 2.0. The prefixes given below are
conventionally used; you could use alternative prefixes if you wish.
Namespace Name Prefix
Namespace URI
XML Schema types xs:
http://www.w3.org/2001/XMLSchema
XPath 2.0 functions fn:
http://www.w3.org/2005/xpath-functions
Typically, these namespaces will be declared on the xsl:stylesheet or xsl:transform
element, as shown in the following listing:
<xsl:stylesheet version="2.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:fn="http://www.w3.org/2005/xpath-functions"
...
</xsl:stylesheet>
The following points should be noted:
·
The Altova XSLT 2.0 Engine uses the XPath 2.0 and XQuery 1.0 Functions namespace
Altova MapForce 2011
© 2011 Altova GmbH
Appendices
Engine information
·
·
·
373
(listed in the table above) as its default functions namespace. So you can use XPath
2.0 and XSLT 2.0 functions in your stylesheet without any prefix. If you declare the
XPath 2.0 Functions namespace in your stylesheet with a prefix, then you can
additionally use the prefix assigned in the declaration.
When using type constructors and types from the XML Schema namespace, the prefix
used in the namespace declaration must be used when calling the type constructor (for
example, xs:date).
With the CRs of 23 January 2007, the untypedAtomic and duration datatypes (
dayTimeDuration and yearMonthDuration), which were formerly in the XPath
Datatypes namespace (typically prefixed xdt:) have been moved to the XML Schema
namespace.
Some XPath 2.0 functions have the same name as XML Schema datatypes. For
example, for the XPath functions fn:string and fn:boolean there exist XML
Schema datatypes with the same local names: xs:string and xs:boolean. So if
you were to use the XPath expression string('Hello'), the expression evaluates
as fn:string('Hello')—not as xs:string('Hello').
Schema-awareness
The Altova XSLT 2.0 Engine is schema-aware.
Whitespace in XML document
By default, the Altova XSLT 2.0 Engine strips all boundary whitespace from
boundary-whitespace-only nodes in the source XML document. The removal of this whitespace
affects the values that the fn:position(), fn:last(), fn:count(), and
fn:deep-equal() functions return. For more details, see Whitespace-only Nodes in XML
Document in the XPath 2.0 and XQuery 1.0 Functions section.
Note: If a boundary-whitespace-only text node is required in the output, then insert the required
whitespace within one of the two adjoining child elements. For example, the XML fragment:
<para>This is <b>bold</b> <i>italic</>.</para>
when processed with the XSLT template
<xsl:template match="para">
<xsl:apply-templates/>
</xsl:template>
will produce:
This is bolditalic.
To get a space between bold and italic in the output, insert a space character within either
the <b> or <i> elements in the XML source. For example:
<para>This is <b>bold</b> <i> italic</>.</para> or
<para>This is <b>bold&#x20;</b> <i>italic</>.</para> or
<para>This is <b>bold</b><i>&#x20;italic</>.</para>
When such an XML fragment is processed with the same XSLT template given above, it will
produce:
This is bold italic.
XSLT 2.0 elements and functions
Limitations and implementation-specific behavior of XSLT 2.0 elements and functions are listed
© 2011 Altova GmbH
Altova MapForce 2011
374
Appendices
Engine information
in the section XSLT 2.0 Elements and Functions.
XPath 2.0 functions
Implementation-specific behavior of XPath 2.0 functions is listed in the section XPath 2.0 and
XQuery 1.0 Functions.
XSLT 2.0 Elements and Functions
Limitations
The xsl:preserve-space and xsl:strip-space elements are not supported.
Implementation-specific behavior
Given below is a description of how the Altova XSLT 2.0 Engine handles
implementation-specific aspects of the behavior of certain XSLT 2.0 functions.
xsl:result-document
Additionally supported encodings are: base16tobinary and base64tobinary.
function-available
The function tests for the availability of in-scope functions (XSLT 2.0, XPath 2.0, and extension
functions).
unparsed-text
The href attribute accepts (i) relative paths for files in the base-uri folder, and (ii) absolute
paths with or without the file:// protocol. Additionally supported encodings are:
binarytobase16 and binarytobase64.
Altova MapForce 2011
© 2011 Altova GmbH
Appendices
Engine information
375
20.1.3 Extensions
Altova Engines (XSLT 1.0, XSLT 2.0, and XQuery 1.0), which are used in a number of Altova
products, support the use of a set of AltovaXML-specific custom extension functions.
Java Extension Functions
A Java extension function can be used within an XPath or XQuery expression to invoke a Java
constructor or call a Java method (static or instance).
A field in a Java class is considered to be a method without any argument. A field can be static
or instance. How to access fields is described in the respective sub-sections, static and
instance.
This section is organized into the following sub-sections:
·
·
·
·
·
Java: Constructors
Java: Static Methods and Static Fields
Java: Instance Methods and Instance Fields
Datatypes: XSLT/XQuery to Java
Datatypes: Java to XSLT/XQuery
Form of the extension function
The extension function in the XPath/XQuery expression must have the form prefix:fname().
·
·
Note:
The prefix: part identifies the extension function as a Java function. It does so by
associating the extension function with an in-scope namespace declaration, the URI of
which must begin with java: (see below for examples). The namespace declaration
should identify a Java class, for example: xmlns:myns="java:java.lang.Math".
However, it could also simply be: xmlns:myns="java" (without a colon), with the
identification of the Java class being left to the fname() part of the extension function.
The fname() part identifies the Java method being called, and supplies the arguments
for the method (see below for examples). However, if the namespace URI identified by
the prefix: part does not identify a Java class (see preceding point), then the Java
class should be identified in the fname() part, before the class and separated from the
class by a period (see the second XSLT example below).
The class being called must be on the classpath of the machine.
XSLT example
Here are two examples of how a static method can be called. In the first example, the class
name (java.lang.Math) is included in the namespace URI and, therefore, must not be in the
fname() part. In the second example, the prefix: part supplies the prefix java: while the
fname() part identifies the class as well as the method.
<xsl:value-of xmlns:jMath="java:java.lang.Math"
select="jMath:cos(3.14)" />
<xsl:value-of xmlns:jmath="java"
select="jmath:java.lang.Math.cos(3.14)" />
The method named in the extension function (cos() in the example above) must match the
name of a public static method in the named Java class (java.lang.Math in the example
above).
© 2011 Altova GmbH
Altova MapForce 2011
376
Appendices
Engine information
XQuery example
Here is an XQuery example similar to the XSLT example above:
<cosine xmlns:jMath="java:java.lang.Math">
{jMath:cos(3.14)}
</cosine>
User-defined Java classes
If you have created your own Java classes, methods in these classes are called differently
according to: (i) whether the classes are accessed via a JAR file or a class file, and (ii) whether
these files (JAR or class) are located in the current directory (the same directory as the XSLT or
XQuery document) or not. How to locate these files is described in the sections User-Defined
Class Files and User-Defined Jar Files. Note that paths to class files not in the current directory
and to all JAR files must be specified.
User-Defined Class Files
If access is via a class file, then there are two possibilities:
·
·
·
·
The class file is in a package. The XSLT or XQuery file is in the same folder as the
Java package.
The class file is not packaged. The XSLT or XQuery file is in the same folder as the
class file.
The class file is in a package. The XSLT or XQuery file is at some random location.
The class file is not packaged. The XSLT or XQuery file is at some random location.
Consider the case where the class file is not packaged and is in the same folder as the XSLT or
XQuery document. In this case, since all classes in the folder are found, the file location does
not need to be specified. The syntax to identify a class is:
java:classname
where
java: indicates that a user-defined Java function is being called; (Java classes in the
current directory will be loaded by default)
classname is the name of the required method's class
The class is identified in a namespace URI, and the namespace is used to prefix a
method call.
Class file packaged, XSLT/XQuery file in same folder as Java package
The example below calls the getVehicleType()method of the Car class of the
com.altova.extfunc package. The com.altova.extfunc package is in the folder
JavaProject. The XSLT file is also in the folder JavaProject.
<xsl:stylesheet version="2.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:fn="http://www.w3.org/2005/xpath-functions"
xmlns:car="java:com.altova.extfunc.Car" >
<xsl:output exclude-result-prefixes="fn car xsl fo xs"/>
<xsl:template match="/">
<a>
<xsl:value-of select="car:getVehicleType()"/>
</a>
Altova MapForce 2011
© 2011 Altova GmbH
Appendices
Engine information
377
</xsl:template>
</xsl:stylesheet>
Class file not packaged, XSLT/XQuery file in same folder as class file
The example below calls the getVehicleType()method of the Car class of the
com.altova.extfunc package. The Car class file is in the following folder location:
JavaProject/com/altova/extfunc. The XSLT file is also in the folder
JavaProject/com/altova/extfunc.
<xsl:stylesheet version="2.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:fn="http://www.w3.org/2005/xpath-functions"
xmlns:car="java:Car" >
<xsl:output exclude-result-prefixes="fn car xsl fo xs"/>
<xsl:template match="/">
<a>
<xsl:value-of select="car:getVehicleType()"/>
</a>
</xsl:template>
</xsl:stylesheet>
Class file packaged, XSLT/XQuery file at any location
The example below calls the getCarColor()method of the Car class of the
com.altova.extfunc package. The com.altova.extfunc package is in the folder
JavaProject. The XSLT file is at any location. In this case, the location of the package must be
specified within the URI as a query string. The syntax is:
java:classname[?path=uri-of-package]
where
java: indicates that a user-defined Java function is being called
uri-of-package is the URI of the Java package
classname is the name of the required method's class
The class is identified in a namespace URI, and the namespace is used to prefix a
method call. The example below shows how to access a class file that is located in
another directory than the current directory.
<xsl:stylesheet version="2.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:fn="http://www.w3.org/2005/xpath-functions"
xmlns:car="
java:com.altova.extfunc.Car?path=file:///C:/JavaProject/" >
<xsl:output exclude-result-prefixes="fn car xsl xs"/>
<xsl:template match="/">
<xsl:variable name="myCar" select="car:new('red')" />
<a><xsl:value-of select="car:getCarColor($myCar)"/></a>
</xsl:template>
© 2011 Altova GmbH
Altova MapForce 2011
378
Appendices
Engine information
</xsl:stylesheet>
Class file not packaged, XSLT/XQuery file at any location
The example below calls the getCarColor()method of the Car class of the
com.altova.extfunc package. The com.altova.extfunc package is in the folder
JavaProject. The XSLT file is at any location. The location of the class file is specified within
the namespace URI as a query string. The syntax is:
java:classname[?path=uri-of-classfile]
where
java: indicates that a user-defined Java function is being called
uri-of-classfile is the URI of the folder containing the class file
classname is the name of the required method's class
The class is identified in a namespace URI, and the namespace is used to prefix a
method call. The example below shows how to access a class file that is located in
another directory than the current directory.
<xsl:stylesheet version="2.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:fn="http://www.w3.org/2005/xpath-functions"
xmlns:car="
java:Car?path=file:///C:/JavaProject/com/altova/extfunc/" >
<xsl:output exclude-result-prefixes="fn car xsl xs"/>
<xsl:template match="/">
<xsl:variable name="myCar" select="car:new('red')" />
<a><xsl:value-of select="car:getCarColor($myCar)"/></a>
</xsl:template>
</xsl:stylesheet>
Note:
When a path is supplied via the extension function, the path is added to the
ClassLoader.
User-Defined Jar Files
If access is via a JAR file, the URI of the JAR file must be specified using the following syntax:
xmlns:classNS="java:classname?path=jar:uri-of-jarfile!/"
The method is then called by using the prefix of the namespace URI that identifies the
class: classNS:method()
In the above:
java: indicates that a Java function is being called
classname is the name of the user-defined class
? is the separator between the classname and the path
path=jar: indicates that a path to a JAR file is being given
uri-of-jarfile is the URI of the jar file
!/ is the end delimiter of the path
classNS:method() is the call to the method
Altova MapForce 2011
© 2011 Altova GmbH
Appendices
Engine information
379
Alternatively, the classname can be given with the method call. Here are two examples of the
syntax:
xmlns:ns1="java:docx.layout.pages?path=jar:file:///c:/projects/docs/docx.jar!/
"
ns1:main()
xmlns:ns2="java?path=jar:file:///c:/projects/docs/docx.jar!/"
ns2:docx.layout.pages.main()
Here is a complete XSLT example that uses a JAR file to call a Java extension function:
<xsl:stylesheet version="2.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:fn="http://www.w3.org/2005/xpath-functions"
xmlns:car="java?path=jar:file:///C:/test/Car1.jar!/" >
<xsl:output exclude-result-prefixes="fn car xsl xs"/>
<xsl:template match="/">
<xsl:variable name="myCar" select="car:Car1.new('red')" />
<a><xsl:value-of select="car:Car1.getCarColor($myCar)"/></a>
</xsl:template>
<xsl:template match="car"/>
</xsl:stylesheet>
Note:
When a path is supplied via the extension function, the path is added to the
ClassLoader.
Java: Constructors
An extension function can be used to call a Java constructor. All constructors are called with the
pseudo-function new().
If the result of a Java constructor call can be implicitly converted to XPath/XQuery datatypes,
then the Java extension function will return a sequence that is an XPath/XQuery datatype. If the
result of a Java constructor call cannot be converted to a suitable XPath/XQuery datatype, then
the constructor creates a wrapped Java object with a type that is the name of the class returning
that Java object. For example, if a constructor for the class java.util.Date is called (
java.util.Date.new()), then an object having a type java.util.Date is returned. The lexical
format of the returned object may not match the lexical format of an XPath datatype and the
value would therefore need to be converted to the lexical format of the required XPath datatype
and then to the required XPath datatype.
There are two things that can be done with a Java object created by a constructor:
·
It can be assigned to a variable:
<xsl:variable name="currentdate" select="date:new()" xmlns:date="
java:java.util.Date" />
·
It can be passed to an extension function (see Instance Method and Instance Fields):
<xsl:value-of select="date:toString(date:new())" xmlns:date="
java:java.util.Date" />
© 2011 Altova GmbH
Altova MapForce 2011
380
Appendices
Engine information
Java: Static Methods and Static Fields
A static method is called directly by its Java name and by supplying the arguments for the
method. Static fields (methods that take no arguments), such as the constant-value fields E
and PI, are accessed without specifying any argument.
XSLT examples
Here are some examples of how static methods and fields can be called:
<xsl:value-of xmlns:jMath="java:java.lang.Math"
select="jMath:cos(3.14)" />
<xsl:value-of xmlns:jMath="java:java.lang.Math"
select="jMath:cos( jMath:PI() )" />
<xsl:value-of xmlns:jMath="java:java.lang.Math"
select="jMath:E() * jMath:cos(3.14)" />
Notice that the extension functions above have the form prefix:fname(). The prefix in all
three cases is jMath:, which is associated with the namespace URI java:java.lang.Math.
(The namespace URI must begin with java:. In the examples above it is extended to contain
the class name (java.lang.Math).) The fname() part of the extension functions must match
the name of a public class (e.g. java.lang.Math) followed by the name of a public static
method with its argument/s (such as cos(3.14)) or a public static field (such as PI()).
In the examples above, the class name has been included in the namespace URI. If it were not
contained in the namespace URI, then it would have to be included in the fname() part of the
extension function. For example:
<xsl:value-of xmlns:java="java:"
select="java:java.lang.Math.cos(3.14)" />
XQuery example
A similar example in XQuery would be:
<cosine xmlns:jMath="java:java.lang.Math">
{jMath:cos(3.14)}
</cosine>
Java: Instance Methods and Instance Fields
An instance method has a Java object passed to it as the first argument of the method call.
Such a Java object typically would be created by using an extension function (for example a
constructor call) or a stylesheet parameter/variable. An XSLT example of this kind would be:
<xsl:stylesheet version="1.0" exclude-result-prefixes="date"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:date="java:java.util.Date"
xmlns:jlang="java:java.lang">
<xsl:param name="CurrentDate" select="date:new()"/>
<xsl:template match="/">
<enrollment institution-id="Altova School"
date="{date:toString($CurrentDate)}"
type="{jlang:Object.toString(jlang:Object.getClass( date:new()
))}">
</enrollment>
</xsl:template>
</xsl:stylesheet>
In the example above, the value of the node enrollment/@type is created as follows:
Altova MapForce 2011
© 2011 Altova GmbH
Appendices
Engine information
381
1. An object is created with a constructor for the class java.util.Date (with the
date:new() constructor).
2. This Java object is passed as the argument of the jlang.Object.getClass method.
3. The object obtained by the getClass method is passed as the argument to the
jlang.Object.toString method.
The result (the value of @type) will be a string having the value: java.util.Date.
An instance field is theoretically different from an instance method in that it is not a Java object
per se that is passed as an argument to the instance field. Instead, a parameter or variable is
passed as the argument. However, the parameter/variable may itself contain the value returned
by a Java object. For example, the parameter CurrentDate takes the value returned by a
constructor for the class java.util.Date. This value is then passed as an argument to the
instance method date:toString in order to supply the value of /enrollment/@date.
Datatypes: XPath/XQuery to Java
When a Java function is called from within an XPath/XQuery expression, the datatype of the
function's arguments is important in determining which of multiple Java classes having the
same name is called.
In Java, the following rules are followed:
·
·
If there is more than one Java method with the same name, but each has a different
number of arguments than the other/s, then the Java method that best matches the
number of arguments in the function call is selected.
The XPath/XQuery string, number, and boolean datatypes (see list below) are implicitly
converted to a corresponding Java datatype. If the supplied XPath/XQuery type can be
converted to more than one Java type (for example, xs:integer), then that Java type
is selected which is declared for the selected method. For example, if the Java method
being called is fx(decimal) and the supplied XPath/XQuery datatype is xs:integer,
then xs:integer will be converted to Java's decimal datatype.
The table below lists the implicit conversions of XPath/XQuery string, number, and boolean
types to Java datatypes.
xs:string
java.lang.String
xs:boolean
boolean (primitive), java.lang.Boolean
xs:integer
int, long, short, byte, float, double, and the
wrapper classes of these, such as java.lang.
Integer
xs:float
float (primitive), java.lang.Float, double
(primitive)
xs:double
double (primitive), java.lang.Double
xs:decimal
float (primitive), java.lang.Float, double
(primitive), java.lang.Double
Subtypes of the XML Schema datatypes listed above (and which are used in XPath and
XQuery) will also be converted to the Java type/s corresponding to that subtype's ancestor type.
In some cases, it might not be possible to select the correct Java method based on the supplied
information. For example, consider the following case.
© 2011 Altova GmbH
Altova MapForce 2011
382
Appendices
·
·
·
·
Engine information
The supplied argument is an xs:untypedAtomic value of 10 and it is intended for the
method mymethod(float).
However, there is another method in the class which takes an argument of another
datatype: mymethod(double).
Since the method names are the same and the supplied type (xs:untypedAtomic)
could be converted correctly to either float or double, it is possible that xs:
untypedAtomic is converted to double instead of float.
Consequently the method selected will not be the required method and might not
produce the expected result. To work around this, you can create a user-defined
method with a different name and use this method.
Types that are not covered in the list above (for example xs:date) will not be converted and will
generate an error. However, note that in some cases, it might be possible to create the required
Java type by using a Java constructor.
Datatypes: Java to XPath/XQuery
When a Java method returns a value, the datatype of the value is a string, numeric or boolean
type, then it is converted to the corresponding XPath/XQuery type. For example, Java's java.
lang.Boolean and boolean datatypes are converted to xsd:boolean.
One-dimensional arrays returned by functions are expanded to a sequence. Multi-dimensional
arrays will not be converted, and should therefore be wrapped.
When a wrapped Java object or a datatype other than string, numeric or boolean is returned,
you can ensure conversion to the required XPath/XQuery type by first using a Java method (e.g
toString) to convert the Java object to a string. In XPath/XQuery, the string can be modified to
fit the lexical representation of the required type and then converted to the required type (for
example, by using the cast as expression).
.NET Extension Functions
If you are working on the .NET platform, you can use extension functions written in any of the
.NET languages (for example, C#). A .NET extension function can be used within an XPath or
XQuery expression to invoke a constructor, property, or method (static or instance) within a
.NET class.
A property of a .NET class is called using the syntax get_PropertyName().
This section is organized into the following sub-sections:
·
·
·
·
·
.NET: Constructors
.NET: Static Methods and Static Fields
.NET: Instance Methods and Instance Fields
Datatypes: XSLT/XQuery to .NET
Datatypes: .NET to XSLT/XQuery
Form of the extension function
The extension function in the XPath/XQuery expression must have the form prefix:fname().
·
·
·
The prefix: part is associated with a URI that identifies the .NET class being
addressed.
The fname() part identifies the constructor, property, or method (static or instance)
within the .NET class, and supplies any argument/s, if required.
The URI must begin with clitype: (which identifies the function as being a .NET
Altova MapForce 2011
© 2011 Altova GmbH
Appendices
Engine information
·
383
extension function).
The prefix:fname() form of the extension function can be used with system classes
and with classes in a loaded assembly. However, if a class needs to be loaded,
additional parameters containing the required information will have to be supplied.
Parameters
To load an assembly, the following parameters are used:
asm
The name of the assembly to be loaded.
ver
The version number (maximum of four integers separated by periods).
sn
The key token of the assembly's strong name (16 hex digits).
from
A URI that gives the location of the assembly (DLL) to be loaded. If the
URI is relative, it is relative to the XSLT or XQuery document. If this
parameter is present, any other parameter is ignored.
partialname
The partial name of the assembly. It is supplied to
Assembly.LoadWith.PartialName(), which will attempt to load the
assembly. If partialname is present, any other parameter is ignored.
loc
The locale, for example, en-US. The default is neutral.
If the assembly is to be loaded from a DLL, use the from parameter and omit the sn parameter.
If the assembly is to be loaded from the Global Assembly Cache (GAC), use the sn parameter
and omit the from parameter.
A question mark must be inserted before the first parameter, and parameters must be
separated by a semi-colon. The parameter name gives its value with an equals sign (see
example below).
Examples of namespace declarations
An example of a namespace declaration in XSLT that identifies the system class
System.Environment:
xmlns:myns="clitype:System.Environment"
An example of a namespace declaration in XSLT that identifies the class to be loaded as
Trade.Forward.Scrip:
xmlns:myns="clitype:Trade.Forward.Scrip?asm=forward;version=10.6.2.1"
An example of a namespace declaration in XQuery that identifies the system class
MyManagedDLL.testClass:. Two cases are distinguished:
1. When the assembly is loaded from the GAC:
declare namespace cs="clitype:MyManagedDLL.testClass?asm=MyManagedDLL;
ver=1.2.3.4;loc=neutral;sn=b9f091b72dccfba8";
2. When the assembly is loaded from the DLL (complete and partial references below):
declare namespace
cs="clitype:MyManagedDLL.testClass?from=file:///C:/Altova
Projects/extFunctions/MyManagedDLL.dll;
declare namespace
cs="clitype:MyManagedDLL.testClass?from=MyManagedDLL.dll;
© 2011 Altova GmbH
Altova MapForce 2011
384
Appendices
Engine information
XSLT example
Here is a complete XSLT example that calls functions in system class System.Math:
<xsl:stylesheet version="2.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:fn="http://www.w3.org/2005/xpath-functions">
<xsl:output method="xml" omit-xml-declaration="yes" />
<xsl:template match="/">
<math xmlns:math="clitype:System.Math">
<sqrt><xsl:value-of select="math:Sqrt(9)"/></sqrt>
<pi><xsl:value-of select="math:PI()"/></pi>
<e><xsl:value-of select="math:E()"/></e>
<pow><xsl:value-of select="math:Pow(math:PI(), math:E())"/></pow>
</math>
</xsl:template>
</xsl:stylesheet>
The namespace declaration on the element math associates the prefix math: with the URI
clitype:System.Math. The clitype: beginning of the URI indicates that what follows
identifies either a system class or a loaded class. The math: prefix in the XPath expressions
associates the extension functions with the URI (and, by extension, the class) System.Math.
The extension functions identify methods in the class System.Math and supply arguments
where required.
XQuery example
Here is an XQuery example fragment similar to the XSLT example above:
<math xmlns:math="clitype:System.Math">
{math:Sqrt(9)}
</math>
As with the XSLT example above, the namespace declaration identifies the .NET class, in this
case a system class. The XQuery expression identifies the method to be called and supplies
the argument.
.NET: Constructors
An extension function can be used to call a .NET constructor. All constructors are called with
the pseudo-function new(). If there is more than one constructor for a class, then the
constructor that most closely matches the number of arguments supplied is selected. If no
constructor is deemed to match the supplied argument/s, then a 'No constructor found'
error is returned.
Constructors that return XPath/XQuery datatypes
If the result of a .NET constructor call can be implicitly converted to XPath/XQuery datatypes,
then the .NET extension function will return a sequence that is an XPath/XQuery datatype.
Constructors that return .NET objects
If the result of a .NET constructor call cannot be converted to a suitable XPath/XQuery
datatype, then the constructor creates a wrapped .NET object with a type that is the name of the
class returning that object. For example, if a constructor for the class System.DateTime is
called (withSystem.DateTime.new()), then an object having a type System.DateTime is
returned.
The lexical format of the returned object may not match the lexical format of a required XPath
datatype. In such cases, the returned value would need to be: (i) converted to the lexical format
Altova MapForce 2011
© 2011 Altova GmbH
Appendices
Engine information
385
of the required XPath datatype; and (ii) cast to the required XPath datatype.
There are three things that can be done with a .NET object created by a constructor:
·
It can be used within a variable:
<xsl:variable name="currentdate" select="date:new(2008, 4, 29)"
xmlns:date="clitype:System.DateTime" />
·
It can be passed to an extension function (see Instance Method and Instance Fields):
<xsl:value-of select="date:ToString(date:new(2008, 4, 29))" xmlns:date
="clitype:System.DateTime" />
·
·
It can be converted to a string, number, or boolean:
<xsl:value-of select="xs:integer(data:get_Month(date:new(2008, 4, 29)))
" xmlns:date="clitype:System.DateTime" />
.NET: Static Methods and Static Fields
A static method is called directly by its name and by supplying the arguments for the method.
The name used in the call must exactly match a public static method in the class specified. If
the method name and the number of arguments that were given in the function call matches
more than one method in a class, then the types of the supplied arguments are evaluated for
the best match. If a match cannot be found unambiguously, an error is reported.
Note:
A field in a .NET class is considered to be a method without any argument. A property
is called using the syntax get_PropertyName().
Examples
An XSLT example showing a call to a method with one argument (System.Math.Sin(arg)):
<xsl:value-of select="math:Sin(30)" xmlns:math="clitype:System.Math"/>
An XSLT example showing a call to a field (considered a method with no argument) (
System.Double.MaxValue()):
<xsl:value-of select="double:MaxValue()" xmlns:double="
clitype:System.Double"/>
An XSLT example showing a call to a property (syntax is get_PropertyName()) (
System.String()):
<xsl:value-of select="string:get_Length('my string')" xmlns:string="
clitype:System.String"/>
An XQuery example showing a call to a method with one argument (System.Math.Sin(arg)):
<sin xmlns:math="clitype:System.Math">
{ math:Sin(30) }
</sin>
.NET: Instance Methods and Instance Fields
An instance method has a .NET object passed to it as the first argument of the method call.
This .NET object typically would be created by using an extension function (for example a
constructor call) or a stylesheet parameter/variable. An XSLT example of this kind would be:
<xsl:stylesheet version="2.0"
© 2011 Altova GmbH
Altova MapForce 2011
386
Appendices
Engine information
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:fn="http://www.w3.org/2005/xpath-functions">
<xsl:output method="xml" omit-xml-declaration="yes"/>
<xsl:template match="/">
<xsl:variable name="releasedate"
select="date:new(2008, 4, 29)"
xmlns:date="clitype:System.DateTime"/>
<doc>
<date>
<xsl:value-of select="date:ToString(date:new(2008, 4, 29))"
xmlns:date="clitype:System.DateTime"/>
</date>
<date>
<xsl:value-of select="date:ToString($releasedate)"
xmlns:date="clitype:System.DateTime"/>
</date>
</doc>
</xsl:template>
</xsl:stylesheet>
In the example above, a System.DateTime constructor (new(2008, 4, 29)) is used to create a
.NET object of type System.DateTime. This object is created twice, once as the value of the
variable releasedate, a second time as the first and only argument of the
System.DateTime.ToString() method. The instance method System.DateTime.ToString()
is called twice, both times with the System.DateTime constructor (new(2008, 4, 29)) as its
first and only argument. In one of these instances, the variable releasedate is used to get the
.NET object.
Instance methods and instance fields
The difference between an instance method and an instance field is theoretical. In an instance
method, a .NET object is directly passed as an argument; in an instance field, a parameter or
variable is passed instead—though the parameter or variable may itself contain a .NET object.
For example, in the example above, the variable releasedate contains a .NET object, and it is
this variable that is passed as the argument of ToString() in the second date element
constructor. Therefore, the ToString() instance in the first date element is an instance
method while the second is considered to be an instance field. The result produced in both
instances, however, is the same.
Datatypes: XPath/XQuery to .NET
When a .NET extension function is used within an XPath/XQuery expression, the datatypes of
the function's arguments are important for determining which one of multiple .NET methods
having the same name is called.
In .NET, the following rules are followed:
·
·
If there is more than one method with the same name in a class, then the methods
available for selection are reduced to those that have the same number of arguments
as the function call.
The XPath/XQuery string, number, and boolean datatypes (see list below) are implicitly
converted to a corresponding .NET datatype. If the supplied XPath/XQuery type can be
converted to more than one .NET type (for example, xs:integer), then that .NET type
is selected which is declared for the selected method. For example, if the .NET method
being called is fx(double) and the supplied XPath/XQuery datatype is xs:integer,
then xs:integer will be converted to .NET's double datatype.
The table below lists the implicit conversions of XPath/XQuery string, number, and boolean
Altova MapForce 2011
© 2011 Altova GmbH
Appendices
Engine information
387
types to .NET datatypes.
xs:string
StringValue, string
xs:boolean
BooleanValue, bool
xs:integer
IntegerValue, decimal, long, integer,
short, byte, double, float
xs:float
FloatValue, float, double
xs:double
DoubleValue, double
xs:decimal
DecimalValue, decimal, double, float
Subtypes of the XML Schema datatypes listed above (and which are used in XPath and
XQuery) will also be converted to the .NET type/s corresponding to that subtype's ancestor type.
In some cases, it might not be possible to select the correct .NET method based on the
supplied information. For example, consider the following case.
·
·
·
·
The supplied argument is an xs:untypedAtomic value of 10 and it is intended for the
method mymethod(float).
However, there is another method in the class which takes an argument of another
datatype: mymethod(double).
Since the method names are the same and the supplied type (xs:untypedAtomic)
could be converted correctly to either float or double, it is possible that xs:
untypedAtomic is converted to double instead of float.
Consequently the method selected will not be the required method and might not
produce the expected result. To work around this, you can create a user-defined
method with a different name and use this method.
Types that are not covered in the list above (for example xs:date) will not be converted and will
generate an error.
Datatypes: .NET to XPath/XQuery
When a .NET method returns a value and the datatype of the value is a string, numeric or
boolean type, then it is converted to the corresponding XPath/XQuery type. For example, .
NET's decimal datatype is converted to xsd:decimal.
When a .NET object or a datatype other than string, numeric or boolean is returned, you can
ensure conversion to the required XPath/XQuery type by first using a .NET method (for
example System.DateTime.ToString()) to convert the .NET object to a string. In XPath/
XQuery, the string can be modified to fit the lexical representation of the required type and then
converted to the required type (for example, by using the cast as expression).
MSXSL Scripts for XSLT
The <msxsl:script> element contains user-defined functions and variables that can be called
from within XPath expressions in the XSLT stylesheet. The <msxsl:script> is a top-level
element, that is, it must be a child element of <xsl:stylesheet> or <xsl:transform>.
The <msxsl:script> element must be in the namespace urn:schemas-microsoft-com:xslt
(see example below).
Scripting language and namespace
© 2011 Altova GmbH
Altova MapForce 2011
388
Appendices
Engine information
The scripting language used within the block is specified in the <msxsl:script> element's
language attribute and the namespace to be used for function calls from XPath expressions is
identified with the implements-prefix attribute (see below).
<msxsl:script language="scripting-language" implements-prefix="user-namespaceprefix">
function-1 or variable-1
...
function-n or variable-n
</msxsl:script>
The <msxsl:script> element interacts with the Windows Scripting Runtime, so only languages
that are installed on your machine may be used within the <msxsl:script> element. The .NET
Framework 2.0 platform or higher must be installed for MSXSL scripts to be used.
Consequently, the .NET scripting languages can be used within the <msxsl:script> element.
The language attribute accepts the same values as the language attribute on the HTML
<script> element. If the language attribute is not specified, then Microsoft JScript is assumed
as the default.
The implements-prefix attribute takes a value that is a prefix of a declared in-scope namespace.
This namespace typically will be a user namespace that has been reserved for a function
library. All functions and variables defined within the <msxsl:script> element will be in the
namespace identified by the prefix specified in the implements-prefix attribute. When a
function is called from within an XPath expression, the fully qualified function name must be in
the same namespace as the function definition.
Example
Here is an example of a complete XSLT stylesheet that uses a function defined within a
<msxsl:script> element.
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:fn="http://www.w3.org/2005/xpath-functions"
xmlns:msxsl="urn:schemas-microsoft-com:xslt"
xmlns:user="http://mycompany.com/mynamespace">
<msxsl:script language="VBScript" implements-prefix="user">
<![CDATA[
' Input: A currency value: the wholesale price
' Returns: The retail price: the input value plus 20% margin,
' rounded to the nearest cent
dim a as integer = 13
Function AddMargin(WholesalePrice) as integer
AddMargin = WholesalePrice * 1.2 + a
End Function
]]>
</msxsl:script>
<xsl:template match="/">
<html>
<body>
<p>
<b>Total Retail Price =
$<xsl:value-of select="user:AddMargin(50)"/>
</b>
Altova MapForce 2011
© 2011 Altova GmbH
Appendices
Engine information
389
<br/>
<b>Total Wholesale Price =
$<xsl:value-of select="50"/>
</b>
</p>
</body>
</html>
</xsl:template>
</xsl:stylesheet>
Datatypes
The values of parameters passed into and out of the script block are limited to XPath datatypes.
This restriction does not apply to data passed among functions and variables within the script
block.
Assemblies
An assembly can be imported into the script by using the msxsl:assembly element. The
assembly is identified via a name or a URI. The assembly is imported when the stylesheet is
compiled. Here is a simple representation of how the msxsl:assembly element is to be used.
<msxsl:script>
<msxsl:assembly name="myAssembly.assemblyName" />
<msxsl:assembly href="pathToAssembly" />
...
</msxsl:script>
The assembly name can be a full name, such as:
"system.Math, Version=3.1.4500.1 Culture=neutral
PublicKeyToken=a46b3f648229c514"
or a short name, such as "myAssembly.Draw".
Namespaces
Namespaces can be declared with the msxsl:using element. This enables assembly classes
to be written in the script without their namespaces, thus saving you some tedious typing. Here
is how the msxsl:using element is used so as to declare namespaces.
<msxsl:script>
<msxsl:using namespace="myAssemblyNS.NamespaceName" />
...
</msxsl:script>
The value of the namespace attribute is the name of the namespace.
Altova Extension Functions
Altova extension functions are in the namespace http://www.altova.com/xslt-extensions
and are indicated in this section with the prefix altova:, which is assumed to be bound to the
namespace given above.
The following extension functions are supported in the current version of your Altova product in
the manner described below. However, note that in future versions of your product, support for
one or more of these functions might be discontinued or the behavior of individual functions
© 2011 Altova GmbH
Altova MapForce 2011
390
Appendices
Engine information
might change. Consult the documentation of future releases for information about support for
Altova extension functions in that release.
General functions
·
·
·
·
·
·
·
·
altova:evaluate()
altova:distinct-nodes()
altova:encode-for-rtf()
altova:xbrl-labels()
altova:xbrl-footnotes()
altova:generate-auto-number()
altova:reset-auto-number()
altova:get-temp-folder()
General Functions
The following extension functions are supported in the current version of your Altova product in
the manner described below. However, note that in future versions of your product, support for
one or more of these functions might be discontinued or the behavior of individual functions
might change. Consult the documentation of future releases for information about support for
Altova extension functions in that release.
·
·
·
·
·
·
·
·
altova:evaluate()
altova:distinct-nodes()
altova:encode-for-rtf()
altova:xbrl-labels()
altova:xbrl-footnotes()
altova:generate-auto-number()
altova:reset-auto-number()
altova:get-temp-folder()
altova:evaluate()
The altova:evaluate() function takes an XPath expression, passed as a string, as its
mandatory argument. It returns the output of the evaluated expression.
altova:evaluate(XPathExp as xs:string)
For example:
altova:evaluate('//Name[1]')
In the example above, note that the expression //Name[1] is passed as a string by enclosing it
in single quotes. The altova:evaluate function returns the contents of the first Name element
in the document.
The altova:evaluate function can take additional (optional) arguments. These arguments are,
respectively, the values of variables with the names p1, p2, p3... pN that can be used in the
XPath expression.
altova:evaluate(XPathExp as xs:string [, p1value ... pNvalue])
where
Altova MapForce 2011
© 2011 Altova GmbH
Appendices
Engine information
391
· the variable names must be of the form pX, X being an integer
· the sequence of the function's arguments, from the second argument onwards
corresponds to the sequence of variables named p1 to pN. So the second argument
will be the value of the variable p1, the third argument that of the variable p2, and so
on.
· The variable values must be of type item*
For example:
<xsl:variable name="xpath" select="'$p3, $p2, $p1'" />
<xsl:value-of select="altova:evaluate( $xpath, 10, 20, 'hi' )" />
Outputs "hi 20 10"
In the above listing, notice the following:
·
·
·
The second argument of the altova:evaluate expression is the value assigned to the
variable $p1, the third argument that assigned to the variable $p2, and so on.
Notice that the fourth argument of the function is a string value, indicated by its being
enclosed in quotes.
The select attribute of the xs:variable element supplies the XPath expression. Since
this expression must be of type xs:string, it is enclosed in single quotes.
The following examples further illustrate usage:
<xsl:variable name="xpath" select="'$p1'" />
<xsl:value-of select="altova:evaluate( $xpath, //Name[1] )" />
Outputs value of the first Name element.
<xsl:variable name="xpath" select="'$p1'" />
<xsl:value-of select="altova:evaluate( $xpath, '//Name[1]' )" />
Outputs "//Name[1]"
The altova:evaluate() extension function is useful in situations where an XPath expression
in the XSLT stylesheet contains one or more parts that must be evaluated dynamically. For
example, consider a situation in which a user enters his request for the sorting criterion and this
criterion is stored in the attribute UserReq/@sortkey. In the stylesheet, you could then have the
expression :
<xsl:sort select="altova:evaluate(../UserReq/@sortkey)" order="ascending"/
>
The altova:evaluate() function reads the sortkey attribute of the UserReq child element of
the parent of the context node. Say the value of the sortkey attribute is Price, then Price is
returned by the altova:evaluate() function and becomes the value of the select attribute:
<xsl:sort select="Price" order="ascending"/>
If this sort instruction occurs within the context of an element called Order, then the Order
elements will be sorted according to the values of their Price children. Alternatively, if the value
of @sortkey were, say, Date, then the Order elements would be sorted according to the values
of their Date children. So the sort criterion for Order is selected from the sortkey attribute at
runtime. This could not have been achieved with an expression like:
<xsl:sort select="../UserReq/@sortkey" order="ascending"/>
In the case shown above, the sort criterion would be the sortkey attribute itself, not Price or
Date (or any other current content of sortkey).
Variables can be used in the altova:evaluate() extension function as shown in the examples
below:
© 2011 Altova GmbH
Altova MapForce 2011
392
Appendices
Engine information
·
Static variables: <xsl:value-of select="$i3, $i2, $i1" />
Outputs the values of three variables.
·
Dynamic XPath expression with dynamic variables:
<xsl:variable name="xpath" select="'$p3, $p2, $p1'" />
<xsl:value-of select="altova:evaluate( $xpath, 10, 20, 30 )" />
Outputs "30 20 10"
·
Dynamic XPath expression with no dynamic variable:
<xsl:variable name="xpath" select="'$p3, $p2, $p1'" />
<xsl:value-of select="altova:evaluate( $xpath )" />
Outputs error: No variable defined for $p3.
Note:
The static context includes namespaces, types, and functions—but not variables—from
the calling environment. The base URI and default namespace are inherited.
altova:distinct-nodes()
The altova:distinct-nodes() function takes a set of one or more nodes as its input and
returns the same set minus nodes with duplicate values. The comparison is done using the
XPath/XQuery function fn:deep-equal.
altova:distinct-nodes( $arg as node()* )
as node()*
altova:encode-for-rtf()
The altova:encode-for-rtf() function converts the input string into code for RTF.
altova:encode-for-rtf( $inputstr as xs:string?,
$preserveallwhitespace as xs:boolean,
$preservenewlines as xs:boolean) as xs:string
Whitespace and new lines will be preserved according to the boolean value specified for their
respective parameters.
altova:xbrl-labels()
The altova:xbrl-labels() function takes two input arguments: a node name and the
taxonomy file location containing the node. The function returns the XBRL labels associated
with the input node.
altova:xbrl-labels( $name as xs:QName, $file as xs:string )
as node()*
altova:xbrl-footnotes()
The altova:footnotes() function takes a node as its input argument and returns the set of
XBRL footnote nodes referenced by the input node.
altova:footnotes( $arg as node() )
as node()*
altova:generate-auto-number(id as xs:string, start-with as xs:integer,
increment as xs:integer, reset-on-change as xs:string)
Altova MapForce 2011
© 2011 Altova GmbH
Appendices
Engine information
393
Generates a series of numbers having the specified ID. The start integer and the increment is
specified.
altova:reset-auto-number(id as xs:string)
This function resets the auto-numbering of the auto-numbering series specified with the ID
argument. The series is reset to the start integer of the series (see
altova:generate-auto-number above).
altova:get-temp-folder as xs:string
Gets the temporary folder.
© 2011 Altova GmbH
Altova MapForce 2011
394
Appendices
20.2
Technical Data
Technical Data
This section contains useful background information on the technical aspects of your software.
It is organized into the following sections:
·
·
·
·
·
OS and Memory Requirements
Altova XML Parser
Altova XSLT and XQuery Engines
Unicode Support
Internet Usage
Altova MapForce 2011
© 2011 Altova GmbH
Appendices
Technical Data
395
20.2.1 OS and Memory Requirements
Operating System
This software application is a 32-bit Windows application that runs on Windows XP, Windows
Server 2003 and 2008, Windows Vista, and Windows 7.
Memory
Since the software is written in C++ it does not require the overhead of a Java Runtime
Environment and typically requires less memory than comparable Java-based applications.
However, each document is loaded fully into memory so as to parse it completely and to
improve viewing and editing speed. The memory requirement increases with the size of the
document.
Memory requirements are also influenced by the unlimited Undo history. When repeatedly
cutting and pasting large selections in large documents, available memory can rapidly be
depleted.
© 2011 Altova GmbH
Altova MapForce 2011
396
Appendices
Technical Data
20.2.2 Altova XML Parser
When opening any XML document, the application uses its built-in validating parser (the Altova
XML Parser) to check for well-formedness, validate the document against a schema (if
specified), and build trees and Infosets. The Altova XML Parser is also used to provide
intelligent editing help while you edit documents and to dynamically display any validation error
that may occur.
The built-in Altova XML Parser implements the Final Recommendation of the W3C's XML
Schema specification. New developments recommended by the W3C's XML Schema Working
Group are continuously being incorporated in the Altova Parser, so that Altova products give
you a state-of-the-art development environment.
Altova MapForce 2011
© 2011 Altova GmbH
Appendices
Technical Data
397
20.2.3 Altova XSLT and XQuery Engines
Altova products use the Altova XSLT 1.0 Engine, Altova XSLT 2.0 Engine, and Altova XQuery
1.0 Engines. Documentation about implementation-specific behavior for each engine is in the
section Engine Information, in Appendix 1 of the product documentation, should that engine be
used in the product.
These three engines are also available in the AltovaXML package, which can be downloaded
from the Altova website free of charge. Documentation for using the engines is available with
the AltovaXML package.
© 2011 Altova GmbH
Altova MapForce 2011
398
Appendices
Technical Data
20.2.4 Unicode Support
Unicode is the new 16-bit character-set standard defined by the Unicode Consortium that
provides a unique number for every character,
· no matter what the platform,
· no matter what the program,
· no matter what the language.
Fundamentally, computers just deal with numbers. They store letters and other characters by
assigning a number for each one. Before Unicode was invented, there were hundreds of
different encoding systems for assigning these numbers. No single encoding could contain
enough characters: for example, the European Union alone requires several different encodings
to cover all its languages. Even for a single language like English, no single encoding was
adequate for all the letters, punctuation, and technical symbols in common use.
These encoding systems used to conflict with one another. That is, two encodings used the
same number for two different characters, or different numbers for the same character. Any
given computer (especially servers) needs to support many different encodings; yet whenever
data is passed between different encodings or platforms, that data always runs the risk of
corruption.
Unicode is changing all that!
Unicode provides a unique number for every character, no matter what the platform, no matter
what the program, and no matter what the language. The Unicode Standard has been adopted
by such industry leaders as Apple, HP, IBM, JustSystem, Microsoft, Oracle, SAP, Sun, Base
and many others.
Unicode is required by modern standards such as XML, Java, ECMAScript (JavaScript), LDAP,
CORBA 3.0, WML, etc., and is the official way to implement ISO/IEC 10646. It is supported in
many operating systems, all modern browsers, and many other products. The emergence of the
Unicode Standard, and the availability of tools supporting it, are among the most significant
recent global software technology trends.
Incorporating Unicode into client-server or multi-tiered applications and web sites offers
significant cost savings over the use of legacy character sets. Unicode enables a single
software product or a single web site to be targeted across multiple platforms, languages and
countries without re-engineering. It allows data to be transported through many different
systems without corruption.
Windows XP
Altova's XML products provide full Unicode support. To edit an XML document, you will also
need a font that supports the Unicode characters being used by that document.
Please note that most fonts only contain a very specific subset of the entire Unicode range and
are therefore typically targeted at the corresponding writing system. Consequently you may
encounter XML documents that contain "unprintable" characters, because the font you have
selected does not contain the required glyphs. Therefore it can sometimes be very useful to
have a font that covers the entire Unicode range - especially when editing XML documents from
all over the world.
The most universal font we have encountered is a typeface called Arial Unicode MS that has
been created by Agfa Monotype for Microsoft. This font contains over 50,000 glyphs and covers
the entire set of characters specified by the Unicode 2.1 standard. It needs 23MB and is
included with Microsoft Office 2000.
Altova MapForce 2011
© 2011 Altova GmbH
Appendices
Technical Data
399
We highly recommend that you install this font on your system and use it with the application if
you are often editing documents in different writing systems. This font is not installed with the
"Typical" setting of the Microsoft Office setup program, but you can choose the Custom Setup
option to install this font.
In the /Examples folder in your application folder you will also find a new XHTML file called
Unicode-UTF8.html that contains the sentence "When the world wants to talk, it speaks
Unicode" in many different languages ("Wenn die Welt miteinander spricht, spricht sie
Unicode") and writing-systems (
) - this line has been
adopted from the 10th Unicode conference in 1997 and is a beautiful illustration of the
importance of Unicode for the XML standard. Opening this file will give you a quick impression
on what is possible with Unicode and what writing systems are supported by the fonts available
on your PC installation.
Right-to-Left Writing Systems
Please note that even under Windows NT 4.0 any text from a right-to-left writing-system (such
as Hebrew or Arabic) is not rendered correctly except in those countries that actually use
right-to-left writing-systems. This is due to the fact that only the Hebrew and Arabic versions of
Windows NT contains support for rendering and editing right-to-left text on the operating system
layer.
© 2011 Altova GmbH
Altova MapForce 2011
400
Appendices
Technical Data
20.2.5 Internet Usage
Altova applications will initiate Internet connections on your behalf in the following situations:
·
·
·
·
·
If you click the "Request evaluation key-code" in the Registration dialog (Help |
Software Activation), the three fields in the registration dialog box are transferred to
our web server by means of a regular http (port 80) connection and the free evaluation
key-code is sent back to the customer via regular SMTP e-mail.
If you use the URL mode of the Open dialog box to open a document directly from a
URL (File | Open | Switch to URL), that document is retrieved through a http (port 80)
connection. (This functionality is available in XMLSpy and Authentic Desktop.)
If you open an XML document that refers to an XML Schema or DTD and the document
is specified through a URL, it is also retrieved through a http (port 80) connection once
you validate the XML document. This may also happen automatically upon opening a
document if you have instructed the application to automatically validate files upon
opening in the File tab of the Options dialog (Tools | Options). (This functionality is
available in XMLSpy and Authentic Desktop.)
If you are using the Send by Mail... command (File | Send by Mail) in XMLSpy, the
current selection or file is sent by means of any MAPI-compliant mail program installed
on the user's PC.
As part of Software Activation and LiveUpdate as further described in this manual and
the Altova Software License Agreement.
Altova MapForce 2011
© 2011 Altova GmbH
Appendices
20.3
License Information
401
License Information
This section contains:
·
·
·
Information about the distribution of this software product
Information about the intellectual property rights related to this software product
The End User License Agreement governing the use of this software product
Please read this information carefully. It is binding upon you since you agreed to these terms
when you installed this software product.
© 2011 Altova GmbH
Altova MapForce 2011
402
Appendices
License Information
20.3.1 Electronic Software Distribution
This product is available through electronic software distribution, a distribution method that
provides the following unique benefits:
·
·
·
·
You can evaluate the software free-of-charge before making a purchasing decision.
Once you decide to buy the software, you can place your order online at the Altova
website and immediately get a fully licensed product within minutes.
When you place an online order, you always get the latest version of our software.
The product package includes a comprehensive integrated onscreen help system. The
latest version of the user manual is available at www.altova.com (i) in HTML format for
online browsing, and (ii) in PDF format for download (and to print if you prefer to have
the documentation on paper).
30-day evaluation period
After downloading this product, you can evaluate it for a period of up to 30 days free of charge.
About 20 days into this evaluation period, the software will start to remind you that it has not yet
been licensed. The reminder message will be displayed once each time you start the
application. If you would like to continue using the program after the 30-day evaluation period,
you have to purchase an Altova Software License Agreement, which is delivered in the form of
a key-code that you enter into the Software Activation dialog to unlock the product. You can
purchase your license at the online shop at the Altova website.
Helping Others within Your Organization to Evaluate the Software
If you wish to distribute the evaluation version within your company network, or if you plan to
use it on a PC that is not connected to the Internet, you may only distribute the Setup programs,
provided that they are not modified in any way. Any person that accesses the software installer
that you have provided, must request their own 30-day evaluation license key code and after
expiration of their evaluation period, must also purchase a license in order to be able to
continue using the product.
For further details, please refer to the Altova Software License Agreement at the end of this
section.
Altova MapForce 2011
© 2011 Altova GmbH
Appendices
License Information
403
20.3.2 Software Activation and License Metering
As part of Altova’s Software Activation, the software may use your internal network and Internet
connection for the purpose of transmitting license-related data at the time of installation,
registration, use, or update to an Altova-operated license server and validating the authenticity
of the license-related data in order to protect Altova against unlicensed or illegal use of the
software and to improve customer service. Activation is based on the exchange of license
related data such as operating system, IP address, date/time, software version, and computer
name, along with other information between your computer and an Altova license server.
Your Altova product has a built-in license metering module that further helps you avoid any
unintentional violation of the End User License Agreement. Your product is licensed either as a
single-user or multi-user installation, and the license-metering module makes sure that no more
than the licensed number of users use the application concurrently.
This license-metering technology uses your local area network (LAN) to communicate between
instances of the application running on different computers.
Single license
When the application starts up, as part of the license metering process, the software sends a
short broadcast datagram to find any other instance of the product running on another computer
in the same network segment. If it doesn't get any response, it will open a port for listening to
other instances of the application.
Multi license
If more than one instance of the application is used within the same LAN, these instances will
briefly communicate with each other on startup. These instances exchange key-codes in order
to help you to better determine that the number of concurrent licenses purchased is not
accidentally violated. This is the same kind of license metering technology that is common in
the Unix world and with a number of database development tools. It allows Altova customers to
purchase reasonably-priced concurrent-use multi-user licenses.
We have also designed the applications so that they send few and small network packets so as
to not put a burden on your network. The TCP/IP ports (2799) used by your Altova product are
officially registered with the IANA (see
http://www.isi.edu/in-notes/iana/assignments/port-numbers for details) and our license-metering
module is tested and proven technology.
If you are using a firewall, you may notice communications on port 2799 between the computers
that are running Altova products. You are, of course, free to block such traffic between different
groups in your organization, as long as you can ensure by other means, that your license
agreement is not violated.
You will also notice that, if you are online, your Altova product contains many useful functions;
these are unrelated to the license-metering technology.
© 2011 Altova GmbH
Altova MapForce 2011
404
Appendices
License Information
20.3.3 Intellectual Property Rights
The Altova Software and any copies that you are authorized by Altova to make are the
intellectual property of and are owned by Altova and its suppliers. The structure, organization
and code of the Software are the valuable trade secrets and confidential information of Altova
and its suppliers. The Software is protected by copyright, including without limitation by United
States Copyright Law, international treaty provisions and applicable laws in the country in which
it is being used. Altova retains the ownership of all patents, copyrights, trade secrets,
trademarks and other intellectual property rights pertaining to the Software, and that Altova’s
ownership rights extend to any images, photographs, animations, videos, audio, music, text and
"applets" incorporated into the Software and all accompanying printed materials. Notifications of
claimed copyright infringement should be sent to Altova’s copyright agent as further provided on
the Altova Web Site.
Altova software contains certain Third Party Software that is also protected by intellectual
property laws, including without limitation applicable copyright laws as described in detail at
http://www.altova.com/legal_3rdparty.html.
All other names or trademarks are the property of their respective owners.
Altova MapForce 2011
© 2011 Altova GmbH
Appendices
License Information
405
20.3.4 Altova End User License Agreement
THIS IS A LEGAL DOCUMENT -- RETAIN FOR YOUR RECORDS
ALTOVA® END USER LICENSE AGREEMENT
Licensor:
Altova GmbH
Rudolfsplatz 13a/9
A-1010 Wien
Austria
Important - Read Carefully. Notice to User:
This End User License Agreement (“Software License Agreement”) is a legal document
between you and Altova GmbH (“Altova”). It is important that you read this document
before using the Altova-provided software (“Software”) and any accompanying
documentation, including, without limitation printed materials, ‘online’ files, or electronic
documentation (“Documentation”). By clicking the “I accept” and “Next” buttons below,
or by installing, or otherwise using the Software, you agree to be bound by the terms of
this Software License Agreement as well as the Altova Privacy Policy (“Privacy Policy”)
including, without limitation, the warranty disclaimers, limitation of liability, data use and
termination provisions below, whether or not you decide to purchase the Software. You
agree that this agreement is enforceable like any written agreement negotiated and
signed by you. If you do not agree, you are not licensed to use the Software, and you must
destroy any downloaded copies of the Software in your possession or control. You may print a
copy of this Software License Agreement as part of the installation process at the time of
acceptance. Alternatively, you may go to our Web site at http://www.altova.com/eula to
download and print a copy of this Software License Agreement for your files and
http://www.altova.com/privacy to review the Privacy Policy.
1. SOFTWARE LICENSE
(a)
License Grant.
(i)
Upon your acceptance of this Software License Agreement Altova grants you a
non-exclusive, non-transferable (except as provided below), limited license, without the right to
grant sublicenses, to install and use a copy of the Software on one compatible personal
computer or workstation up to the Permitted Number of computers. Subject to the limitations set
forth in Section 1(c), you may install and use a copy of the Software on more than one of your
compatible personal computers or workstations if you have purchased a Named User license.
The Permitted Number of computers and/or users shall be determined and specified at such
time as you elect to purchase the Software. During the evaluation period, hereinafter defined,
only a single user may install and use the software on one (1) personal computer or
workstation. If you have licensed the Software as part of a suite of Altova software products
(collectively, the “Suite”) and have not installed each product individually, then the Software
License Agreement governs your use of all of the software included in the Suite.
(ii)
If you have licensed SchemaAgent, then the terms and conditions of this
Software License Agreement apply to your use of the SchemaAgent server software
(“SchemaAgent Server”) included therein, as applicable, and you are licensed to use
SchemaAgent Server solely in connection with your use of Altova Software and solely for the
purposes described in the accompanying documentation.
(iii)
If you have licensed Software that enables users to generate source code, your
license to install and use a copy of the Software as provided herein permits you to generate
source code based on (i) Altova Library modules that are included in the Software (such
generated code hereinafter referred to as the “Restricted Source Code”) and (ii) schemas or
© 2011 Altova GmbH
Altova MapForce 2011
406
Appendices
License Information
mappings that you create or provide (such code as may be generated from your schema or
mapping source materials hereinafter referred to as the “Unrestricted Source Code”). In
addition to the rights granted herein, Altova grants you a non-exclusive, non-transferable, limited
license to compile the complete generated code (comprised of the combination of the
Restricted Source Code and the Unrestricted Source Code) into executable object code form,
and to use, copy, distribute or license that executable. You may not distribute or redistribute,
sublicense, sell, or transfer the Restricted Source Code to a third-party unless said third-party
already has a license to the Restricted Source Code through their separate agreement with
Altova. Notwithstanding anything to the contrary herein, you may not distribute, incorporate or
combine with other software, or otherwise use the Altova Library modules or Restricted Source
Code, or any Altova intellectual property embodied in or associated with the Altova Library
modules or Restricted Source Code, in any manner that would subject the Restricted Source
Code to the terms of a copyleft, free software or open source license that would require the
Restricted Source Code or Altova Library modules source code to be disclosed in source code
form. Altova reserves all other rights in and to the Software. With respect to the feature(s) of
UModel that permit reverse-engineering of your own source code or other source code that you
have lawfully obtained, such use by you does not constitute a violation of this Agreement.
Except as otherwise expressly permitted in Section 1(i) reverse engineering of the Software is
strictly prohibited as further detailed therein.
(iv)
In the event Restricted Source Code is incorporated into executable object
code form, you will include the following statement in (1) introductory splash screens, or if none,
within one or more screens readily accessible by the end-user, and (2) in the electronic and/or
hard copy documentation: “Portions of this program were developed using Altova® [name of
Altova Software, e.g. MapForce® 2011] and include libraries owned by Altova GmbH, Copyright
© 2007-2011 Altova GmbH (www.altova.com).”
(b)
Server Use. You may install one (1) copy of the Software on a computer file server
within your internal network solely for the purpose of downloading and installing the Software
onto other computers within your internal network up to the Permitted Number of computers in a
commercial environment only. If you have licensed SchemaAgent, then you may install
SchemaAgent Server on any server computer or workstation and use it in connection with your
Software. No other network use is permitted, including without limitation using the Software
either directly or through commands, data or instructions from or to a computer not part of your
internal network, for Internet or Web-hosting services or by any user not licensed to use this
copy of the Software through a valid license from Altova.
If you have purchased Concurrent User Licenses as defined in Section 1(d), and subject to
limits set forth therein, you may install a copy of the Software on a terminal server (Microsoft
Terminal Server, Citrix Metaframe, etc.), application virtualization server (Microsoft App-V, Citrix
XenApp, VMWare ThinApp, etc.) or virtual machine environment within your internal network for
the sole and exclusive purpose of permitting individual users within your organization to access
and use the Software through a terminal server, application virtualization session, or virtual
machine environment from another computer provided that the total number of users that
access or use the Software concurrently at any given point in time on such network, virtual
machine or terminal server does not exceed the Permitted Number; and provided that the total
number of users authorized to use the Software through the terminal server, application
virtualization session, or virtual machine environment does not exceed six (6) times the
Permitted Number of users. Accordingly, the limitations set forth in Section 1(d) regarding the
number of installations and the requirement that the usage be on the same physical network
shall not apply to terminal server, application virtualization session, or virtual machine
environments. Altova makes no warranties or representations about the performance of Altova
software in a terminal server, application virtualization session, or virtual machine environment
and the foregoing are expressly excluded from the limited warranty in Section 5 hereof and
technical support is not available with respect to issues arising from use in such environments.
(c)
Named Use. If you have licensed the “Named User” version of the software, you may
Altova MapForce 2011
© 2011 Altova GmbH
Appendices
License Information
407
install the Software on up to five (5) compatible personal computers or workstations of which
you are the primary user thereby allowing you to switch from one computer to the other as
necessary provided that only one (1) instance of the Software will be used by you as the Named
User at any given time. If you have purchased multiple Named User licenses, each individual
Named User will receive a separate license key code.
(d)
Concurrent Use. If you have licensed a “Concurrent-User” version of the Software,
you may install the Software on any compatible computers in a commercial environment only,
up to ten (10) times the Permitted Number of users, provided that only the Permitted Number of
users actually use the Software at the same time and further provided that the computers on
which the Software is installed are on the same physical computer network. The Permitted
Number of concurrent users shall be delineated at such time as you elect to purchase the
Software licenses. Each separate physical network or office location requires its own set of
separate Concurrent User Licenses for those wishing to use the Concurrent User versions of
the Software in more than one location or on more than one network, all subject to the above
Permitted Number limitations and based on the number of users using the Software. If a
computer is not on the same physical network, then a locally installed user license is required.
Home User restrictions and limitations with respect to the Concurrent User licenses used on
home computers are set forth in Section 1(f).
(e)
Backup and Archival Copies. You may make one (1) backup and one (1) archival
copy of the Software, provided your backup and archival copies are not installed or used on any
computer and further provided that all such copies shall bear the original and unmodified
copyright, patent and other intellectual property markings that appear on or in the Software. You
may not transfer the rights to a backup or archival copy unless you transfer all rights in the
Software as provided under Section 3.
(f)
Home Use (Personal and Non-Commercial). In order to further familiarize yourself
with the Software and allow you to explore its features and functions, you, as the primary user of
the computer on which the Software is installed for commercial purposes, may also install one
copy of the Software on only one (1) home personal computer (such as your laptop or desktop)
solely for your personal and non-commercial (“HPNC”) use. This HPNC copy may not be used
in any commercial or revenue-generating business activities, including without limitation,
work-from-home, teleworking, telecommuting, or other work-related use of the Software. The
HPNC copy of the Software may not be used at the same time on a home personal computer
as the Software is being used on the primary computer.
(g)
Key Codes, Upgrades and Updates. Prior to your purchase and as part of the
registration for the thirty (30) day evaluation period, as applicable, you will receive an evaluation
key code. You will receive a purchase key code when you elect to purchase the Software from
either Altova GmbH or an authorized reseller. The purchase key code will enable you to activate
the Software beyond the initial evaluation period. You may not re-license, reproduce or
distribute any key code except with the express written permission of Altova. If the Software that
you have licensed is an upgrade or an update, then the latest update or upgrade that you
download and install replaces all or part of the Software previously licensed. The update or
upgrade and the associated license keys does not constitute the granting of a second license to
the Software in that you may not use the upgrade or updated copy in addition to the copy of the
Software that it is replacing and whose license has terminated.
(h)
Title. Title to the Software is not transferred to you. Ownership of all copies of the
Software and of copies made by you is vested in Altova, subject to the rights of use granted to
you in this Software License Agreement. As between you and Altova, documents, files,
stylesheets, generated program code (including the Unrestricted Source Code) and schemas
that are authored or created by you via your utilization of the Software, in accordance with its
Documentation and the terms of this Software License Agreement, are your property unless
they are created using Evaluation Software, as defined in Section 4 of this Agreement, in which
case you have only a limited license to use any output that contains generated program code
© 2011 Altova GmbH
Altova MapForce 2011
408
Appendices
License Information
(including Unrestricted Source Code) such as Java, C++, C#, VB.NET or XSLT and associated
project files and build scripts, as well as generated XML, XML Schemas, documentation, UML
diagrams, and database structures only for the thirty (30) day evaluation period.
(i)
Reverse Engineering. Except and to the limited extent as may be otherwise
specifically provided by applicable law in the European Union, you may not reverse engineer,
decompile, disassemble or otherwise attempt to discover the source code, underlying ideas,
underlying user interface techniques or algorithms of the Software by any means whatsoever,
directly or indirectly, or disclose any of the foregoing, except to the extent you may be expressly
permitted to decompile under applicable law in the European Union, if it is essential to do so in
order to achieve operability of the Software with another software program, and you have first
requested Altova to provide the information necessary to achieve such operability and Altova
has not made such information available. Altova has the right to impose reasonable conditions
and to request a reasonable fee before providing such information. Any information supplied by
Altova or obtained by you, as permitted hereunder, may only be used by you for the purpose
described herein and may not be disclosed to any third party or used to create any software
which is substantially similar to the expression of the Software. Requests for information from
users in the European Union with respect to the above should be directed to the Altova
Customer Support Department.
(j)
Other Restrictions. You may not loan, rent, lease, sublicense, distribute or otherwise
transfer all or any portion of the Software to third parties except to the limited extent set forth in
Section 3 or as otherwise expressly provided. You may not copy the Software except as
expressly set forth above, and any copies that you are permitted to make pursuant to this
Software License Agreement must contain the same copyright, patent and other intellectual
property markings that appear on or in the Software. You may not modify, adapt or translate
the Software. You may not, directly or indirectly, encumber or suffer to exist any lien or security
interest on the Software; knowingly take any action that would cause the Software to be placed
in the public domain; or use the Software in any computer environment not specified in this
Software License Agreement.
You will comply with applicable law and Altova’s instructions regarding the use of the
Software. You agree to notify your employees and agents who may have access to the
Software of the restrictions contained in this Software License Agreement and to ensure their
compliance with these restrictions.
(k)
THE SOFTWARE IS NEITHER GUARANTEED NOR WARRANTED TO BE
ERROR-FREE NOR SHALL ANY LIABILITY BE ASSUMED BY ALTOVA IN THIS RESPECT.
NOTWITHSTANDING ANY SUPPORT FOR ANY TECHNICAL STANDARD, THE
SOFTWARE IS NOT INTENDED FOR USE IN OR IN CONNECTION WITH, WITHOUT
LIMITATION, THE OPERATION OF NUCLEAR FACILITIES, AIRCRAFT NAVIGATION,
COMMUNICATION SYSTEMS, AIR TRAFFIC CONTROL EQUIPMENT, MEDICAL DEVICES
OR LIFE SUPPORT SYSTEMS, MEDICAL OR HEALTH CARE APPLICATIONS, OR OTHER
APPLICATIONS WHERE THE FAILURE OF THE SOFTWARE OR ERRORS IN DATA
PROCESSING COULD LEAD TO DEATH, PERSONAL INJURY OR SEVERE PHYSICAL OR
ENVIRONMENTAL DAMAGE. YOU AGREE THAT YOU ARE SOLELY RESPONSIBLE FOR
THE ACCURACY AND ADEQUACY OF THE SOFTWARE AND ANY DATA GENERATED OR
PROCESSED BY THE SOFTWARE FOR YOUR INTENDED USE AND YOU WILL DEFEND,
INDEMNIFY AND HOLD ALTOVA, ITS OFFICERS AND EMPLOYEES HARMLESS FROM
ANY 3RD PARTY CLAIMS, DEMANDS, OR SUITS THAT ARE BASED UPON THE
ACCURACY AND ADEQUACY OF THE SOFTWARE IN YOUR USE OR ANY DATA
GENERATED BY THE SOFTWARE IN YOUR USE.
2. INTELLECTUAL PROPERTY RIGHTS
Acknowledgement of Altova's Rights. You acknowledge that the Software and any copies
that you are authorized by Altova to make are the intellectual property of and are owned by
Altova MapForce 2011
© 2011 Altova GmbH
Appendices
License Information
409
Altova and its suppliers. The structure, organization and code of the Software are the valuable
trade secrets and confidential information of Altova and its suppliers. The Software is protected
by copyright, including without limitation by United States Copyright Law, international treaty
provisions and applicable laws in the country in which it is being used. You acknowledge that
Altova retains the ownership of all patents, copyrights, trade secrets, trademarks and other
intellectual property rights pertaining to the Software, and that Altova’s ownership rights extend
to any images, photographs, animations, videos, audio, music, text and “applets” incorporated
into the Software and all accompanying printed materials. You will take no actions which
adversely affect Altova’s intellectual property rights in the Software. Trademarks shall be used
in accordance with accepted trademark practice, including identification of trademark owners’
names. Trademarks may only be used to identify printed output produced by the Software, and
such use of any trademark does not give you any right of ownership in that trademark.
XMLSpy®, Authentic®, StyleVision®, MapForce®, UModel®, DatabaseSpy®, DiffDog®,
SchemaAgent®, SemanticWorks®, MissionKit®, Markup Your Mind®, Nanonull™, and Altova®
are trademarks of Altova GmbH. (registered in numerous countries). Unicode and the Unicode
Logo are trademarks of Unicode, Inc. Windows, Windows XP, Windows Vista, and Windows 7
are trademarks of Microsoft. W3C, CSS, DOM, MathML, RDF, XHTML, XML and XSL are
trademarks (registered in numerous countries) of the World Wide Web Consortium (W3C);
marks of the W3C are registered and held by its host institutions, MIT, INRIA and Keio. Except
as expressly stated above, this Software License Agreement does not grant you any intellectual
property rights in the Software. Notifications of claimed copyright infringement should be sent to
Altova’s copyright agent as further provided on the Altova Web Site.
3. LIMITED TRANSFER RIGHTS
Notwithstanding the foregoing, you may transfer all your rights to use the Software to another
person or legal entity provided that: (a) you also transfer each of this Software License
Agreement, the Software and all other software or hardware bundled or pre-installed with the
Software, including all copies, updates and prior versions, and all copies of font software
converted into other formats, to such person or entity; (b) you retain no copies, including
backups and copies stored on a computer; (c) the receiving party secures a personalized key
code from Altova; and (d) the receiving party accepts the terms and conditions of this Software
License Agreement and any other terms and conditions upon which you legally purchased a
license to the Software. Notwithstanding the foregoing, you may not transfer education,
pre-release, or not-for-resale copies of the Software.
4. PRE-RELEASE AND EVALUATION PRODUCT ADDITIONAL TERMS
If the product you have received with this license is pre-commercial release or beta Software
(“Pre-release Software”), then this Section applies. In addition, this section applies to all
evaluation and/or demonstration copies of Altova software (“Evaluation Software”) and
continues in effect until you purchase a license. To the extent that any provision in this section is
in conflict with any other term or condition in this Software License Agreement, this section shall
supersede such other term(s) and condition(s) with respect to the Pre-release and/or Evaluation
Software, but only to the extent necessary to resolve the conflict. You acknowledge that the
Pre-release Software is a pre-release version, does not represent final product from Altova, and
may contain bugs, errors and other problems that could cause system or other failures and data
loss. CONSEQUENTLY, THE PRE-RELEASE AND/OR EVALUATION SOFTWARE IS
PROVIDED TO YOU “AS-IS” WITH NO WARRANTIES FOR USE OR PERFORMANCE, AND
ALTOVA DISCLAIMS ANY WARRANTY OR LIABILITY OBLIGATIONS TO YOU OF ANY
KIND, WHETHER EXPRESS OR IMPLIED. WHERE LEGALLY LIABILITY CANNOT BE
EXCLUDED FOR PRE-RELEASE AND/OR EVALUATION SOFTWARE, BUT IT MAY BE
LIMITED, ALTOVA’S LIABILITY AND THAT OF ITS SUPPLIERS SHALL BE LIMITED TO THE
SUM OF FIFTY DOLLARS (USD $50) IN TOTAL. If the Evaluation Software has a time-out
feature, then the software will cease operation after the conclusion of the designated evaluation
period. Upon such expiration date, your license will expire unless otherwise extended. Your
license to use any output created with the Evaluation Software that contains generated program
© 2011 Altova GmbH
Altova MapForce 2011
410
Appendices
License Information
code (including Unrestricted Source Code) such as Java, C++, C, VB.NET or XSLT and
associated project files and build scripts as well as generated XML, XML Schemas,
documentation, UML diagrams, and database structures terminates automatically upon the
expiration of the designated evaluation period but the license to use such output is revived upon
your purchase of a license for the Software that you evaluated and used to create such output.
Access to any files created with the Evaluation Software is entirely at your risk. You
acknowledge that Altova has not promised or guaranteed to you that Pre-release Software will
be announced or made available to anyone in the future, that Altova has no express or implied
obligation to you to announce or introduce the Pre-release Software, and that Altova may not
introduce a product similar to or compatible with the Pre-release Software. Accordingly, you
acknowledge that any research or development that you perform regarding the Pre-release
Software or any product associated with the Pre-release Software is done entirely at your own
risk. During the term of this Software License Agreement, if requested by Altova, you will
provide feedback to Altova regarding testing and use of the Pre-release Software, including
error or bug reports. If you have been provided the Pre-release Software pursuant to a
separate written agreement, your use of the Software is governed by such agreement. You
may not sublicense, lease, loan, rent, distribute or otherwise transfer the Pre-release Software.
Upon receipt of a later unreleased version of the Pre-release Software or release by Altova of a
publicly released commercial version of the Software, whether as a stand-alone product or as
part of a larger product, you agree to return or destroy all earlier Pre-release Software received
from Altova and to abide by the terms of the license agreement for any such later versions of
the Pre-release Software.
5. LIMITED WARRANTY AND LIMITATION OF LIABILITY
(a)
Limited Warranty and Customer Remedies. Altova warrants to the person or entity
that first purchases a license for use of the Software pursuant to the terms of this Software
License Agreement that (i) the Software will perform substantially in accordance with any
accompanying Documentation for a period of ninety (90) days from the date of receipt, and (ii)
any support services provided by Altova shall be substantially as described in Section 6 of this
agreement. Some states and jurisdictions do not allow limitations on duration of an implied
warranty, so the above limitation may not apply to you. To the extent allowed by applicable law,
implied warranties on the Software, if any, are limited to ninety (90) days. Altova’s and its
suppliers’ entire liability and your exclusive remedy shall be, at Altova’s option, either (i) return of
the price paid, if any, or (ii) repair or replacement of the Software that does not meet Altova’s
Limited Warranty and which is returned to Altova with a copy of your receipt. This Limited
Warranty is void if failure of the Software has resulted from accident, abuse, misapplication,
abnormal use, Trojan horse, virus, or any other malicious external code. Any replacement
Software will be warranted for the remainder of the original warranty period or thirty (30) days,
whichever is longer. This limited warranty does not apply to Evaluation and/or Pre-release
Software.
(b)
No Other Warranties and Disclaimer. THE FOREGOING LIMITED WARRANTY
AND REMEDIES STATE THE SOLE AND EXCLUSIVE REMEDIES FOR ALTOVA OR ITS
SUPPLIER’S BREACH OF WARRANTY. ALTOVA AND ITS SUPPLIERS DO NOT AND
CANNOT WARRANT THE PERFORMANCE OR RESULTS YOU MAY OBTAIN BY USING
THE SOFTWARE. EXCEPT FOR THE FOREGOING LIMITED WARRANTY, AND FOR ANY
WARRANTY, CONDITION, REPRESENTATION OR TERM TO THE EXTENT WHICH THE
SAME CANNOT OR MAY NOT BE EXCLUDED OR LIMITED BY LAW APPLICABLE TO YOU
IN YOUR JURISDICTION, ALTOVA AND ITS SUPPLIERS MAKE NO WARRANTIES,
CONDITIONS, REPRESENTATIONS OR TERMS, EXPRESS OR IMPLIED, WHETHER BY
STATUTE, COMMON LAW, CUSTOM, USAGE OR OTHERWISE AS TO ANY OTHER
MATTERS. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, ALTOVA AND
ITS SUPPLIERS DISCLAIM ALL OTHER WARRANTIES AND CONDITIONS, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, SATISFACTORY QUALITY,
INFORMATIONAL CONTENT OR ACCURACY, QUIET ENJOYMENT, TITLE AND
Altova MapForce 2011
© 2011 Altova GmbH
Appendices
License Information
411
NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE, AND THE PROVISION OF OR
FAILURE TO PROVIDE SUPPORT SERVICES. THIS LIMITED WARRANTY GIVES YOU
SPECIFIC LEGAL RIGHTS.
YOU MAY HAVE OTHERS, WHICH VARY FROM
STATE/JURISDICTION TO STATE/JURISDICTION.
(c)
Limitation of Liability. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE
LAW EVEN IF A REMEDY FAILS ITS ESSENTIAL PURPOSE, IN NO EVENT SHALL ALTOVA
OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL, DIRECT, INDIRECT OR
CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF
BUSINESS INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE
USE OF OR INABILITY TO USE THE SOFTWARE OR THE PROVISION OF OR FAILURE TO
PROVIDE SUPPORT SERVICES, EVEN IF ALTOVA HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES. IN ANY CASE, ALTOVA’S ENTIRE LIABILITY UNDER
ANY PROVISION OF THIS SOFTWARE LICENSE AGREEMENT SHALL BE LIMITED TO
THE AMOUNT ACTUALLY PAID BY YOU FOR THE SOFTWARE PRODUCT. Because some
states and jurisdictions do not allow the exclusion or limitation of liability, the above limitation
may not apply to you. In such states and jurisdictions, Altova’s liability shall be limited to the
greatest extent permitted by law and the limitations or exclusions of warranties and liability
contained herein do not prejudice applicable statutory consumer rights of person acquiring
goods otherwise than in the course of business. The disclaimer and limited liability above are
fundamental to this Software License Agreement between Altova and you.
(d)
Infringement Claims. Altova will indemnify and hold you harmless and will defend or
settle any claim, suit or proceeding brought against you by a third party that is based upon a
claim that the content contained in the Software infringes a copyright or violates an intellectual
or proprietary right protected by United States or European Union law (“Claim”), but only to the
extent the Claim arises directly out of the use of the Software and subject to the limitations set
forth in Section 5 of this Agreement except as otherwise expressly provided. You must notify
Altova in writing of any Claim within ten (10) business days after you first receive notice of the
Claim, and you shall provide to Altova at no cost such assistance and cooperation as Altova
may reasonably request from time to time in connection with the defense of the Claim. Altova
shall have sole control over any Claim (including, without limitation, the selection of counsel and
the right to settle on your behalf on any terms Altova deems desirable in the sole exercise of its
discretion). You may, at your sole cost, retain separate counsel and participate in the defense
or settlement negotiations. Altova shall pay actual damages, costs, and attorney fees awarded
against you (or payable by you pursuant to a settlement agreement) in connection with a Claim
to the extent such direct damages and costs are not reimbursed to you by insurance or a third
party, to an aggregate maximum equal to the purchase price of the Software. If the Software or
its use becomes the subject of a Claim or its use is enjoined, or if in the opinion of Altova’s legal
counsel the Software is likely to become the subject of a Claim, Altova shall attempt to resolve
the Claim by using commercially reasonable efforts to modify the Software or obtain a license to
continue using the Software. If in the opinion of Altova’s legal counsel the Claim, the injunction
or potential Claim cannot be resolved through reasonable modification or licensing, Altova, at its
own election, may terminate this Software License Agreement without penalty, and will refund to
you on a pro rata basis any fees paid in advance by you to Altova. THE FOREGOING
CONSTITUTES ALTOVA’S SOLE AND EXCLUSIVE LIABILITY FOR INTELLECTUAL
PROPERTY INFRINGEMENT. This indemnity does not apply to infringements that would not be
such, except for customer-supplied elements.
6. SUPPORT AND MAINTENANCE
Altova offers multiple optional “Support & Maintenance Package(s)” (“SMP”) for the version of
Software product edition that you have licensed, which you may elect to purchase in addition to
your Software license. The Support Period, hereinafter defined, covered by such SMP shall be
delineated at such time as you elect to purchase a SMP. Your rights with respect to support
and maintenance as well as your upgrade eligibility depend on your decision to purchase SMP
© 2011 Altova GmbH
Altova MapForce 2011
412
Appendices
License Information
and the level of SMP that you have purchased:
(a)
If you have not purchased SMP, you will receive the Software AS IS and will not receive
any maintenance releases or updates. However, Altova, at its option and in its sole discretion
on a case by case basis, may decide to offer maintenance releases to you as a courtesy, but
these maintenance releases will not include any new features in excess of the feature set at the
time of your purchase of the Software. In addition, Altova will provide free technical support to
you for thirty (30) days after the date of your purchase (the “Support Period” for the purposes of
this paragraph 6(a), and Altova, in its sole discretion on a case by case basis, may also provide
free courtesy technical support during your thirty (30) day evaluation period. Technical support
is provided via a Web-based support form only, and there is no guaranteed response time.
(b)
If you have purchased SMP, then solely for the duration of its delineated Support
Period, you are eligible to receive the version of the Software edition that you have
licensed and all maintenance releases and updates for that edition that are released during your
Support Period. For the duration of your SMP’s Support Period, you will also be eligible to
receive upgrades to the comparable edition of the next version of the Software that succeeds
the Software edition that you have licensed for applicable upgrades released during your
Support Period. The specific upgrade edition that you are eligible to receive based on your
Support Period is further detailed in the SMP that you have purchased. Software that is
introduced as separate product is not included in SMP. Maintenance releases, updates and
upgrades may or may not include additional features. In addition, Altova will provide Priority
Technical Support to you for the duration of the Support Period. Priority Technical Support is
provided via a Web-based support form only and Altova will make commercially reasonable
efforts to respond via e-mail to all requests within forty-eight (48) hours during Altova’s business
hours (MO-FR, 8am UTC – 10pm UTC, Austrian and US holidays excluded) and to make
reasonable efforts to provide work-arounds to errors reported in the Software.
During the Support Period you may also report any Software problem or error to Altova. If Altova
determines that a reported reproducible material error in the Software exists and significantly
impairs the usability and utility of the Software, Altova agrees to use reasonable commercial
efforts to correct or provide a usable work-around solution in an upcoming maintenance release
or update, which is made available at certain times at Altova’s sole discretion.
If Altova, in its discretion, requests written verification of an error or malfunction discovered by
you or requests supporting example files that exhibit the Software problem, you shall promptly
provide such verification or files, by email, telecopy, or overnight mail, setting forth in reasonable
detail the respects in which the Software fails to perform. You shall use reasonable efforts to
cooperate in diagnosis or study of errors. Altova may include error corrections in maintenance
releases, updates, or new major releases of the Software. Altova is not obligated to fix errors
that are immaterial. Immaterial errors are those that do not significantly impact use of the
Software as determined by Altova in its sole discretion. Whether or not you have purchased the
Support & Maintenance Package, technical support only covers issues or questions resulting
directly out of the operation of the Software and Altova will not provide you with generic
consultation, assistance, or advice under any circumstances.
Updating Software may require the updating of software not covered by this Software License
Agreement before installation. Updates of the operating system and application software not
specifically covered by this Software License Agreement are your responsibility and will not be
provided by Altova under this Software License Agreement. Altova’s obligations under this
Section 6 are contingent upon your proper use of the Software and your compliance with the
terms and conditions of this Software License Agreement at all times. Altova shall be under no
obligation to provide the above technical support if, in Altova’s opinion, the Software has failed
due to the following conditions: (i) damage caused by the relocation of the software to another
location or CPU; (ii) alterations, modifications or attempts to change the Software without Altova
’s written approval; (iii) causes external to the Software, such as natural disasters, the failure or
fluctuation of electrical power, or computer equipment failure; (iv) your failure to maintain the
Altova MapForce 2011
© 2011 Altova GmbH
Appendices
License Information
413
Software at Altova’s specified release level; or (v) use of the Software with other software
without Altova’s prior written approval. It will be your sole responsibility to: (i) comply with all
Altova-specified operating and troubleshooting procedures and then notify Altova immediately of
Software malfunction and provide Altova with complete information thereof; (ii) provide for the
security of your confidential information; (iii) establish and maintain backup systems and
procedures necessary to reconstruct lost or altered files, data or programs.
7. SOFTWARE ACTIVATION, UPDATES AND LICENSE METERING
(a)
License Metering. Altova has a built-in license metering module that helps you to
avoid any unintentional violation of this Software License Agreement. Altova may use your
internal network for license metering between installed versions of the Software.
(b)
Software Activation. Altova’s Software may use your internal network and
Internet connection for the purpose of transmitting license-related data at the time of
installation, registration, use, or update to an Altova-operated license server and
validating the authenticity of the license-related data in order to protect Altova against
unlicensed or illegal use of the Software and to improve customer service. Activation is
based on the exchange of license related data between your computer and the Altova
license server. You agree that Altova may use these measures and you agree to follow
any applicable requirements. You further agree that use of license key codes that are
not or were not generated by Altova and lawfully obtained from Altova, or an authorized
reseller as part of an effort to activate or use the Software violates Altova’s intellectual
property rights as well as the terms of this Software License Agreement. You agree that
efforts to circumvent or disable Altova’s copyright protection mechanisms or license
management mechanism violate Altova’s intellectual property rights as well as the terms
of this Software License Agreement. Altova expressly reserves the rights to seek all
available legal and equitable remedies to prevent such actions and to recover lost
profits, damages and costs.
(c)
LiveUpdate. Altova provides a new LiveUpdate notification service to you, which is
free of charge. Altova may use your internal network and Internet connection for the purpose of
transmitting license-related data to an Altova-operated LiveUpdate server to validate your
license at appropriate intervals and determine if there is any update available for you.
(d)
Use of Data. The terms and conditions of the Privacy Policy are set out in full at
http://www.altova.com/privacy and are incorporated by reference into this Software License
Agreement. By your acceptance of the terms of this Software License Agreement and/or use of
the Software, you authorize the collection, use and disclosure of information collected by Altova
for the purposes provided for in this Software License Agreement and/or the Privacy Policy.
Altova has the right in its sole discretion to amend this provision of the Software License
Agreement and/or Privacy Policy at any time. You are encouraged to review the terms of the
Privacy Policy as posted on the Altova Web site from time to time.
(e)
Notice to European Users. Please note that the information as described in
paragraph 7(d) above may be transferred outside of the European Economic Area, for purposes
of processing, analysis, and review, by Altova, Inc., a company located in Beverly,
Massachusetts, U.S.A., or its subsidiaries or Altova’s subsidiaries or divisions, or authorized
partners, located worldwide. You are advised that the United States uses a sectoral model of
privacy protection that relies on a mix of legislation, governmental regulation, and
self-regulation. You are further advised that the Council of the European Union has found that
this model does not provide "adequate" privacy protections as contemplated by Article 25 of the
European Union's Data Directive. (Directive 95/46/EC, 1995 O.J. (L 281) 31). Article 26 of the
European Union's Data Directive allows for transfer of personal data from the European Union
to a third country if the individual has unambiguously given his consent to the transfer of
personal information, regardless of the third country's level of protection. By agreeing to this
Software License Agreement, you consent to the transfer of all such information to the United
© 2011 Altova GmbH
Altova MapForce 2011
414
Appendices
License Information
States and the processing of that information as described in this Software License Agreement
and the Privacy Policy.
8. TERM AND TERMINATION
This Software License Agreement may be terminated (a) by your giving Altova written notice of
termination; (b) by Altova, at its option, giving you written notice of termination if you commit a
breach of this Software License Agreement and fail to cure such breach within ten (10) days
after notice from Altova; or (c) at the request of an authorized Altova reseller in the event that
you fail to make your license payment or other monies due and payable. In addition the
Software License Agreement governing your use of a previous version that you have upgraded
or updated of the Software is terminated upon your acceptance of the terms and conditions of
the Software License Agreement accompanying such upgrade or update. Upon any termination
of the Software License Agreement, you must cease all use of the Software that this Software
License Agreement governs, destroy all copies then in your possession or control and take such
other actions as Altova may reasonably request to ensure that no copies of the Software remain
in your possession or control. The terms and conditions set forth in Sections 1(h), 1(i), 1(j), 1(k),
2, 5(b), 5(c), 5(d), 7(d), 7(e), 9, 10 and 11 survive termination as applicable.
9. RESTRICTED RIGHTS NOTICE AND EXPORT RESTRICTIONS
The Software was developed entirely at private expense and is commercial computer software
provided with RESTRICTED RIGHTS. Use, duplication or disclosure by the U.S. Government
or a U.S. Government contractor or subcontractor is subject to the restrictions set forth in this
Agreement and as provided in FAR 12.211 and 12.212 (48 C.F.R. §12.211 and 12.212) or
DFARS 227. 7202 (48 C.F.R. §227-7202) as applicable. Consistent with the above as
applicable, Commercial Computer Software and Commercial Computer Documentation
licensed to U.S. government end users only as commercial items and only with those rights as
are granted to all other end users under the terms and conditions set forth in this Software
License Agreement. Manufacturer is Altova GmbH, Rudolfsplatz, 13a/9, A-1010 Vienna,
Austria/EU. You may not use or otherwise export or re-export the Software or Documentation
except as authorized by United States law and the laws of the jurisdiction in which the Software
was obtained. In particular, but without limitation, the Software or Documentation may not be
exported or re-exported (i) into (or to a national or resident of) any U.S. embargoed country or
(ii) to anyone on the U.S. Treasury Department's list of Specially Designated Nationals or the
U.S. Department of Commerce's Table of Denial Orders. By using the Software, you represent
and warrant that you are not located in, under control of, or a national or resident of any such
country or on any such list.
10. THIRD PARTY SOFTWARE
The Software may contain third party software which requires notices and/or additional terms
and conditions. Such required third party software notices and/or additional terms and
conditions are located at our Website at http://www.altova.com/legal_3rdparty.html and are
made a part of and incorporated by reference into this Agreement. By accepting this
Agreement, you are also accepting the additional terms and conditions, if any, set forth therein.
11. GENERAL PROVISIONS
If you are located in the European Union and are using the Software in the European Union and
not in the United States, then this Software License Agreement will be governed by and
construed in accordance with the laws of the Republic of Austria (excluding its conflict of laws
principles and the U.N. Convention on Contracts for the International Sale of Goods) and you
expressly agree that exclusive jurisdiction for any claim or dispute with Altova or relating in any
way to your use of the Software resides in the Handelsgericht, Wien (Commercial Court,
Vienna) and you further agree and expressly consent to the exercise of personal jurisdiction in
the Handelsgericht, Wien (Commercial Court, Vienna) in connection with any such dispute or
Altova MapForce 2011
© 2011 Altova GmbH
Appendices
License Information
415
claim.
If you are located in the United States or are using the Software in the United States then this
Software License Agreement will be governed by and construed in accordance with the laws of
the Commonwealth of Massachusetts, USA (excluding its conflict of laws principles and the
U.N. Convention on Contracts for the International Sale of Goods) and you expressly agree that
exclusive jurisdiction for any claim or dispute with Altova or relating in any way to your use of the
Software resides in the federal or state courts of the Commonwealth of Massachusetts and you
further agree and expressly consent to the exercise of personal jurisdiction in the federal or
state courts of the Commonwealth of Massachusetts in connection with any such dispute or
claim.
If you are located outside of the European Union or the United States and are not using the
Software in the United States, then this Software License Agreement will be governed by and
construed in accordance with the laws of the Republic of Austria (excluding its conflict of laws
principles and the U.N. Convention on Contracts for the International Sale of Goods) and you
expressly agree that exclusive jurisdiction for any claim or dispute with Altova or relating in any
way to your use of the Software resides in the Handelsgericht, Wien (Commercial Court,
Vienna) and you further agree and expressly consent to the exercise of personal jurisdiction in
the Handelsgericht Wien (Commercial Court, Vienna) in connection with any such dispute or
claim. This Software License Agreement will not be governed by the conflict of law rules of any
jurisdiction or the United Nations Convention on Contracts for the International Sale of Goods,
the application of which is expressly excluded.
This Software License Agreement contains the entire agreement and understanding of the
parties with respect to the subject matter hereof, and supersedes all prior written and oral
understandings of the parties with respect to the subject matter hereof. Any notice or other
communication given under this Software License Agreement shall be in writing and shall have
been properly given by either of us to the other if sent by certified or registered mail, return
receipt requested, or by overnight courier to the address shown on Altova’s Web site for Altova
and the address shown in Altova’s records for you, or such other address as the parties may
designate by notice given in the manner set forth above. This Software License Agreement will
bind and inure to the benefit of the parties and our respective heirs, personal and legal
representatives, affiliates, successors and permitted assigns. The failure of either of us at any
time to require performance of any provision hereof shall in no manner affect such party’s right
at a later time to enforce the same or any other term of this Software License Agreement. This
Software License Agreement may be amended only by a document in writing signed by both of
us. In the event of a breach or threatened breach of this Software License Agreement by either
party, the other shall have all applicable equitable as well as legal remedies. Each party is duly
authorized and empowered to enter into and perform this Software License Agreement. If, for
any reason, any provision of this Software License Agreement is held invalid or otherwise
unenforceable, such invalidity or unenforceability shall not affect the remainder of this Software
License Agreement, and this Software License Agreement shall continue in full force and effect
to the fullest extent allowed by law. The parties knowingly and expressly consent to the
foregoing terms and conditions.
Last updated: 2011-06-08
© 2011 Altova GmbH
Altova MapForce 2011
Index
Index
417
function - using named templates, 277
functions, 171
Altova Engines,
in Altova products, 397
Altova extension functions,
chart functions (see chart functions), 390
(
general functions, 390
(default),
multi input / output components, 48
.
Altova extensions,
chart functions (see chart functions), 389
Altova website, 366
Altova XML,
DoTransform.bat, 32
Altova XML Parser,
about, 396
.NET extension functions,
constructors, 384
datatype conversions, .NET to XPath/XQuery, 387
datatype conversions, XPath/XQuery to .NET, 386
for XSLT and XQuery, 382
Altova XSLT 1.0 Engine,
limitations and implementation-specific behavior, 370
Altova XSLT 2.0 Engine,
general information about, 372
information about, 372
instance methods, instance fields, 385
overview, 382
Annotate,
comment a mapping, 75
static methods, static fields, 385
Annotation,
comments on connectors, 75
connector, 345
<
<dynamic>,
file input / output, 48
A
About MapForce, 366
abs, 320
Absolute,
paths - advantages / disadvantages, 124
Accelerator,
shortcut keys, 357
Activating the software, 365
Add, 297
duplicate before / after, 341
global resource file, 94
schema location, 341
user-def. functions, 239
Adjust-to-Timezone, 317
Aggregate,
© 2011 Altova GmbH
Annotation settings,
connector, 75
anyURI,
functions, 314
Application workflow,
using global resources, 104
Assign,
global resource to component, 97
ATTLIST,
DTD namespace URIs, 197
Autoconnect,
child items, 55, 87
Auto-mapping,
child elements, 87
auto-number, 293
avg, 281
B
Background Information, 394
backwards compatibility,
of XSLT 2.0 Engine, 372
418
Index
Base,
type - derived types, 203
and absolute path, 33
and input parameters, 180
base-uri, 314
default file output name, 32
input parameters, 180
Best fit,
double click resize icon, 18
BOM,
Byte Order Mark, 341
Bool,
output if false, 266
boolean, 283
comparing input nodes, 174
Builder,
user-defined function, 239
Byte Order Mark,
in component settings, 341
C
Call,
template, 272
Call graphs,
SPS stylesheet, 226
Casting,
to target schema, 341
Catalog,
file, 199
ceiling, 297
Chained,
mapping - code generation, 144
Change,
configuration - global resource, 99
character entities,
in HTML output of XSLT transformation, 370
char-from-code, 303
Check,
type checking, 198
Child items,
autoconnect, 55, 87
Deleting, 87
Children,
standard with children, 83
Code,
exit code - command line, 178
inline functions & code size, 248
strip schema names from, 341
Code generation,
make paths absolute, 124
of chained mappings, 144
wrapper class version, 357
code-from-char, 303
Command line,
default and preview settings, 182
dynamic input file names, 118
exit code, 178
input parameter, 180
Input parameters, 121
parameters, 178
parameters and input values, 180
Command line parameters,
wildcards in quotes, 180
Comment,
a mapping / connector, 75
Companion software,
for download, 366
compare, 321
compl.,
complement node set, 28
Complex,
function - inline, 248
User-defined complex input, 256
User-defined complex output, 261
User-defined function, 255, 261
Component,
assign global resource, 97
change database, 341
changing settings, 341
deleted items, 57
enable input processing, 341
encoding, 54
encoding settings, 341
input - default value, 182
item context menu, 54
multi input / Output, 116
multi-file input / output, 47
mutli input / Output, 118
pretty pring in output, 341
resize to best fit, 18
schema, 54
search in, 54
Component download center,
© 2011 Altova GmbH
Index
Component download center,
at Altova web site, 366
419
priority, 65
priority context, 175
Components,
multi file input/output, 48
Context menu,
item context menu, 54
Compute once,
variable, 153
Conversion,
functions - boolean, 174
Compute when,
variable, 153
type checking, 198
concat, 303
Copy,
existing connector elsewhere - CTRL, 55
Concatenate,
filters - don't, 162
Copy all,
mapping method, 70
Condition,
extendable IF-Else, 339
Copy-all,
and filters, 84
connectors, 84
Configuration,
add to global resource, 94
copy existing, 94
switch - global resource, 99
Connection,
Deleting, 87
move parent/child connectors, 87
properties, 87
settings, 345
Connections,
type driven, 84
Connector,
add comment to, 75
annotate, 75
copying using CTRL, 55
include descendent connectionis, 87
mapping with, 55
naming, 345
popup, 55
properties, 87
Connector icon,
popup, 55
Connectors,
copy-all, 84
resolve / delete connectors, 84
Copyright information, 401
Core,
library functions, 281
count, 281
count() function,
in XPath 1.0, 370
count, sum, avg,
aggregate function, 171
Create,
function, 24
user-defined function, 239
current, 326
current-date, 316
current-dateTime, 316
current-time, 316
Custom,
function, 65
lilbrary, 65
XSLT 2.0 functions, 276
XSLT functions, 272
Cut,
move parent/child connectors, 87
Consolidating data,
merging XML files, 176
Constant,
as default value, 182
Constructor,
XSLT2, 276
constructors,
xs:ENTITY, 315
contains, 303
Context,
override, 189
© 2011 Altova GmbH
D
Data,
filtering, 28
Database,
and multiple sources, 341
change DB, 341
component, 54
420
Database,
strip schema names from code, 341
Index
file names as Input parameters, 121
input files at runtime, 118
Datatype,
explicit - implicit, 276
Date,
XSLT 2.0 constructor, 276
Default,
configuration - global resource, 94
input value, 266
parameter - input component, 182
default functions namespace,
in XSLT 2.0 stylesheets, 372
default-collation, 316
Definition file,
globalresource.xml, 92
Delete,
connections, 87
copy-all connections, 84
deletions - missing items, 57
user-defined function, 239
Derived,
types - using / mapping to, 203
Descendent,
connections - include, 87
distinct-values, 302
Distribution,
of Altova's software products, 401, 402, 404
divide, 297
document, 326
Documentation,
defining SPS stylesheets, 229
Documenting,
mappings, 220
document-uri, 314
DoTransform,
AltovaXML batch file, 32
DoTransform bat,
transforming XML, 36
Driver,
JDBC, 341
DTD,
source and target, 197
Duplicate,
add before/after, 341
connector - use CTRL, 55
input item, 42
Dynamic,
and multifile support, 116
E
EDI,
validating, 61
Edit, 338
Element,
cast to target, 341
element-available, 326
Enable input processing,
optimization, 341
Encoding,
Byte Order Mark, 341
component, 54
component settings, 341
End User License Agreement, 401, 405
ends-with, 321
equal, 295
equal-or-greater, 295
equal-or-less, 295
Erase,
delete user-defined func., 239
Error,
validation, 61
Errorlevel,
command line execution, 178
escape-uri, 321
Evaluation key,
for your Altova software, 365
Evaluation period,
of Altova's software products, 401, 402, 404
Examples,
tutorial folder, 16
Exist,
use not-exist to map missing nodes, 187
exists, 299
node test, 185
Exit code, 178
Explicit,
datatype, 276
Export,
user-defined function, 239
Expression,
regular, 310
© 2011 Altova GmbH
Index
421
Extending,
function parameters, 65
adding custom XSLT 2.0, 276
aggregate, 171
Extension functions for XSLT and XQuery, 375
Changing type of user-defined, 239
complex - inline, 248
Extension Functions in .NET for XSLT and XQuery,
see under .NET extension functions, 382
Extension Functions in Java for XSLT and XQuery,
see under Java extension functions, 375
Extension Functions in MSXSL scripts, 387
conversion - boolean, 174
core library, 281
custom, 65
defining, 238
exporting user-defined, 239
extendable, 65
F
extendable IF-Else, 339
find in library, 65
false, 315
inline, 248
input as parameter, 180
FAQs on MapForce, 366
File, 335
add resource configuration, 94
catalog, 199
define global resource, 94
multi file input / output, 48
File:,
(default), 48
item in component, 48
Files,
dynamic file names as Input, 121
multiple from database, 122
Filter,
complement, 28
component - tips, 162
concatenate - don't, 162
copy-all connector, 84
data, 28
map parent items, 162
merging XML files, 176
priority context, 162
Find,
function in library, 65
item in component, 54
XSLT - Output tab, 338
floor, 297
Folders,
as a global resource, 101
format-dateTime, 283
format-number, 283, 326
From, 317
Function, 293, 350
adding, 65
adding custom XSLT, 272
© 2011 Altova GmbH
library, 65
nested user-defined, 266
Query, 65
restrictions in user-defined, 239
standard user-defined function, 250
sum, 277
user-defined, 239
user-defined - changing type, 239
user-defined function, 207
user-defined look-up function, 250
visual builder, 239
xpath2 library, 314
xslt library, 324
function-available, 326
functions,
importing user-defined, 239
mapping to, 24
reference section, 280
see under XSLT 2.0 functions, 374
Functions used by, 226
G
Generate,
code & inline functions, 248
multiple target Java, 36
multiple target XSLT, 36
XML Schema automatically, 18
Generated,
file output name, 32
generate-id, 326
get-fileext, 291
422
get-folder, 291
Global resource,
activate, 99
assign to component, 97
copy configuration, 94
default configuration, 94
folders as, 101
properties, 111
start workflow, 108
workflow, 104
Global resources,
define resource file, 94
definition file, 92
toolbar, 93
Index
extendable, 339
Impact analysis,
SPS stylesheet, 226
implementation-specific behavior,
of XSLT 2.0 functions, 374
Implicit,
datatype, 276
Import,
user-def. functions, 239
Include,
XSLT, 272
XSLT 2.0, 276
in-context,
parameter, 281
Globalresource.xml,
resource definition, 92
Inline, 239
functions and code size, 248
greater, 295
Inline / Standard,
user-defined functions, 248
group-adjacent, 302
group-by, 302
group-ending-with, 302
Groups,
loops and hierarchies, 130
group-starting-with, 302
H
Health Level 7,
example, 236
Help,
see Onscreen Help, 364
Help menu, 363
Hierarchies,
loops and groups, 130
HL7 2.6 to 3.x,
example, 236
Hotkeys,
shortcuts, 357
How to..., 158
HTML,
mapping documentation, 220
I
IF-Else,
Input,
as command line param, 180
command line parameter, 182
comparing boolean nodes, 174
default value, 266
multi file, 118
optional parameters, 266
XML instance, 341
Input component,
default value, 182
Input icon,
mapping, 55
Input parameter,
and code generation, 180
and dynamic file names, 121
command line, 180
dynamic, 118
Insert, 339
Installation,
examples folder, 16
Instance,
input XML instance, 341
output XML instance, 341
Intermediate variables, 148
Internet usage,
in Altova products, 400
Introduction to MapForce, 3
is-xsi-nil, 299
Item,
context menu, 54
© 2011 Altova GmbH
Index
Item,
duplicating, 42
find in component, 54
missing, 57
schema - mapping, 21
Iteration,
priority context, 175
J
Java,
generate multiple target, 36
multiple targets, 33
Java extension functions,
constructors, 379
datatype conversions, Java to Xpath/XQuery, 382
datatype conversions, XPath/XQuery to Java, 381
for XSLT and XQuery, 375
instance methods, instance fields, 380
overview, 375
static methods, static fields, 380
user-defined class files, 376
user-defined JAR files, 378
423
last() function,
in XPath 1.0, 370
Legal information, 401
less, 295
Libraries,
and user-defined functions, 239
Library,
adding XSLT 2.0 functions, 276
adding XSLT functions, 272
custom, 65
defining, 238
find function in, 65
function, 65
function reference, 280
import user-def. functions, 239
XPath2, 65
License, 405
information about, 401
License metering,
in Altova products, 403
Licenses,
for your Altova software, 365
Local,
schemas - catalog files, 199
local-name, 319, 324
logical-and, 295
logical-not, 295
K
Keeping data,
when using value-map, 167
Keeping data unchanged,
passing through a value-map, 167
Keyboard,
shortcuts, 357
logical-or, 295
Lookup table,
mapping missing nodes, 187
properties, 170
value map table, 164
Loops,
groups and hierarchies, 130
lower-case, 321
Key-codes,
for your Altova software, 365
M
L
Label,
connector, 75
lang, 319, 324
Languages,
and dynamic/multi file support, 116
last, 316, 324
© 2011 Altova GmbH
main-mfd-filepath, 291
Make paths,
absolute in generated code, 124
manespace-uri, 319
MapForce,
introduction, 3
Overview, 10
terminology, 12
424
Mapping,
child elements, 87
commenting connectors, 75
connnector, 55
creating source driven, 75
Documenting, 220
Index
Missing items, 57
Missing nodes,
mapping missing nodes, 187
Mixed,
content mapping, 72
content mapping example, 81
no. of connections, 55
predefined SPS stylesheets for documentation, 226
content mapping method, 70
create mixed content, 75
properties, 87
schema items, 21
source-driven mapping, 72
standard mapping, 83
source driven - mixed content, 72
standard mapping, 83
text nodes, 75
target driven, 83
target schema name, 32
modulus, 297
Move,
parent/child connectors, 87
tutorial, 16
type driven, 84
Move down,
item in component, 341
validate structure, 61
validation, 61
Move up,
item in component, 341
Mapping methods,
standard / mixed / copy all, 70
MSXML 6.0,
library, 357
MappingMap,
toTargetSchemaName, 32
msxsl:script, 387
Marked items,
missing items, 57
matches, 321
max, 281
Memory requirements, 395
Menu,
connection, 345
edit, 338
file, 335
function, 350
insert, 339
output, 353
tools, 357
view, 355
Merge,
multiple input files, 118
Merging,
XML files, 176
mfd-filepath, 291
MFF,
and user-defined functions, 239
min, 281
min, max,
aggregate function, 171
Multi,
file support - languages, 116
input / output, 116
Multi file,
input / output, 118
processing (tutorial), 48
Multi-file,
input / output, 47
Multiple,
source schemas, 341
target schemas, 33
targets and Java, 33
viewing multiple target schemas, 36
multiple input,
items, 42
Multiple source,
to single target, 176
to single target item, 38
Multiple XML files,
from single XML source, 122
multiply, 297
MyDocuments,
example files, 16
minOccurs/maxOccurs,
input processing optimization, 341
© 2011 Altova GmbH
Index
425
index of, 364
searching, 364
N
Name, 319, 324
connector, 75, 345
Named,
template - namespaces, 272
Named template,
summing nodes, 277
Namespace,
named template, 272
Namespace URI,
DTD, 197
namespaces,
in XSLT 2.0 stylesheet, 372
namespace-uri, 324
Nested,
user-defined functions, 266
nil,
xsi:nil, 232
node, 319
comparing boolean, 174
find in component, 54
mapping missing nodes, 187
position, 189
removing text nodes, 75
summing multiple, 277
testing, 185
Node set,
complement, 28
node-name, 314
normalize-space, 303
normalize-unicode, 321
Not exist,
mapping missing nodes, 187
not-equal, 295
not-exists, 299
Null,
nillable, 232
number, 283, 319
table of contents, 364
Optimization,
enable input processing, 341
Optional,
input parameters, 266
Ordering Altova software, 365
OS,
for Altova products, 395
Ouput,
save data from, 36
Output, 353
add schema location to output, 341
multi file, 118
parameter, 266
user-defined if bool = false, 266
validate, 61
validating, 61
XML instance, 341
Output icon,
mapping, 55
Overall documentation,
SPS stylesheet, 226
Override,
context, 189
Overview of MapForce, 10
P
Parameter,
and code generation, 180
command line, 178, 180
default value, 182
extending in functions, 65
in-context, 281
input - dynamic, 118
Input function as a, 180, 182
optional, 266
output, 266
using wildcards, 180
O
Onscreen help,
© 2011 Altova GmbH
Parent,
mapping and filters, 162
Parent context,
variable, 153
parse-dateTime, 283
426
Index
parse-number, 283
Regex, 310
Parser,
built into Altova products, 396
Registering your Altova software, 365
Regular expressions, 310
Passing through data,
unchanged through value-map, 167
Relative,
paths - advantages, 124
Path,
absolute when generating code, 33
Remove,
Connection, 87
copy-all connections, 84
PDF,
mapping documentation, 220
remove-fileext, 291
Platforms,
for Altova products, 395
remove-folder, 291
replace, 321
position, 299, 316, 324
node / context, 189
replace-fileext, 291
Resize,
component "best fit", 18
position() function,
in XPath 1.0, 370
Pretty print,
in output component, 341
Preview,
input component value, 182
Priority,
and filters, 162
function, 65
Priority context,
defining, 175
Processors,
for download, 366
Properties,
value map table, 170
Q
qname-related,
functions, 320
Question mark,
missing items, 57
Quotes,
and command line params, 180
R
resolve-filepath, 291
resolve-uri, 314
Resource,
folder, 101
global resource properties, 111
Result of Transformation,
global resources, 104
Retaining data,
passing through vlaue-map, 167
Right-to-left writing systems, 399
Root,
element of target, 173
round, 297
round-half-to-even, 320
round-precision, 297
RTF,
mapping documentation, 220
S
Save,
data in Output window, 36
Schema,
add location to output, 341
auto-generate from XML file, 18
catalog file, 199
components, 54
Recursive,
user-defined function, 207
database component, 54
multiple source, 341
multiple target, 33
Reference, 334
functions in MapForce, 280
name, strip from generated code, 341
viewing multiple targets, 36
© 2011 Altova GmbH
Index
Schema names,
strip from table names, 341
Scripts in XSLT/XQuery,
see under Extension functions, 375
Search,
in components, 54
XSLT - Output tab, 338
427
defining SPS stylesheets for mappings, 229
Substitute,
missing node, 185
substitute-missing, 299
substitute-missing-with-xsi-nil, 299
substring, 303
substring-after, 303, 321
Sequence,
postition, 189
substring-before, 303, 321
Subtract, 297, 317
set-empty, 302
Setting,
connector, 345
sum, 281
nodes in XSLT 1.0, 277
Settings,
changing component, 341
Support for MapForce, 366
Switch,
configuration - global resource, 99
set-xsi-nil, 299
system-property, 326
Shortcut,
keyboard, 357
Single target,
multiple sources, 176
T
Software product license, 405
Source file,
split into multiple target files, 122
Table,
lookup - value map, 164
Source-driven,
- mixed content mapping, 72
creating mapping, 75
text node settings, 75
vs. standard mapping, 83
Specify value,
input component - preview, 182
SPS,
predefined stylesheets for documenting mappings, 226
user-defined stylesheets, 229
Standard,
mapping method, 70
mapping with children, 83
mixed content mapping, 83
user-defined function, 250
vs source-driven mapping, 83
XSLT library, 65
starts-with, 303, 321
string, 283, 314
string-join, 281
string-length, 303
Strip,
schema names, 341
Stylesheets,
defining for documentation, 229
Stylevision,
© 2011 Altova GmbH
strip schema names, 341
strip schema names from, 341
Target,
multiple schemas, 33
root element, 173
viewing multiple schemas, 36
Target file,
multiple from single source file, 122
Target item,
mapping multi-source, 38
Target-driven,
mapping, 83
Technical Information, 394
Technical support for MapForce, 366
Teminology, 12
Template,
calling, 272
named - summing, 277
Test,
node testing, 185
Text,
nodes in mixed content, 75
removing text nodes, 75
Tokenize, 303, 307
Tokenize-by-length, 303, 307
tokenize-regexp, 303
428
Toolbar,
global resource, 93
Tools, 357
Transform,
DoTransform.bat, 36
input data - value map, 164
translate, 303
true, 315
Tutorial, 16
examples folder, 16
Type,
cast to target type, 341
Type conversion,
checking, 198
Type driven,
connections, 84
Types,
derived types - xsi:type, 203
U
Unicode,
support in Altova products, 398
Unicode support,
in Altova products, 398, 399
unparsed-entity-uri, 326
upper-case, 321
URI,
in DTDs, 197
User defined,
changing function type, 239
complex input, 256
complex output, 261
deleting, 239
function - inline / standard, 248
function - standard, 250
Index
User-defined,
functions, 239
functions & mffs, 239
user-defined function,
recursive, 207
Using,
global resources, 99
V
Validate,
data in output window, 36
mapping project, 61
output data, 61
Validator,
in Altova products, 396
Value,
default, 266
input component - preview, 182
Value-Map,
lookup table, 164
lookup table - properties, 170
passing data unchanged, 167
Variable,
inserting, 148
intermediate variable, 148
use cases, 148
Version,
wrapper class compatibility, 357
View, 355
Visual function builder, 239
Visual Studio,
versions supported - code generation, 357
functions, 239
W
functions - complex, 255, 261
functions - restrictions, 239
functions changing type of, 239
Warning,
validation, 61
importing/exporting, 239
whitespace in XML document,
handling by Altova XSLT 2.0 Engine, 372
look-up functions, 250
nested functions, 266
output if bool = false, 266
User manual,
see also Onscreen Help, 364
whitespace nodes in XML document,
and handling by XSLT 1.0 Engine, 370
Wildcards,
use of quotes in command line, 180
© 2011 Altova GmbH
Index
Windows,
support for Altova products, 395
Word,
mapping documentation, 220
Workflow,
start - global resource, 108
using global resource, 104
Wrapper,
classes, 357
Wrapper classes,
version compatibility, 357
X
Xerces,
libraries, 357
XML,
generate XML Schema from, 18
XML files,
from single XML source, 122
XML instance,
absolute path, 33
input, 341
output, 341
XML Parser,
about, 396
XML schema,
automatically generate, 18
xpath, 324
summing multiple nodes, 277
xpath2,
library, 65
library functions, 314
XQuery,
Extension functions, 375
functions, 65
XQuery processor,
in Altova products, 397
xs:,
constuctors, 315
xs:date, 316
xs:time, 316
Xsi:nil,
nillable, 232
xsi:type,
mapping to derived types, 203
© 2011 Altova GmbH
429
xsl:preserve-space, 370
xsl:strip-space, 370
XSLT,
adding custom functions, 272
Extension functions, 375
generate multiple target, 36
library functions, 324
standard library, 65
template namespace, 272
XSLT 1.0 Engine,
limitations and implementation-specific behavior, 370
XSLT 1.0/2.0,
DoTransfrom batch file, 32
generate (tutorial), 32
XSLT 2.0,
adding custom functions, 276
XSLT 2.0 Engine,
general information about, 372
information about, 372
XSLT 2.0 functions,
implementation-specific behavior of, 374
see under fn: for specific functions, 374
XSLT 2.0 stylesheet,
namespace declarations in, 372
XSLT processors,
in Altova products, 397
XSLT2.0,
date constructor, 276