Altova MapForce 2017 Professional Edition

Altova MapForce 2017 Professional Edition
User and Reference Manual
Altova MapForce 2017 Professional Edition
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: 2017
© 2017 Altova GmbH
Table of Contents
1
Altova MapForce 2017 Professional Edition
3
1.1
What's new...
................................................................................................................. 4
2
Introduction
2.1
What Is .................................................................................................................
MapForce?
13
2.2
Basic Concepts
................................................................................................................. 19
2.3
User Interface
.................................................................................................................
Overview
21
2.4
Conventions
................................................................................................................. 29
3
Tutorials
3.1
Convert .................................................................................................................
XML to New Schema
33
3.2
Map Multiple
.................................................................................................................
Sources to One Target
44
3.3
Work with
.................................................................................................................
Multiple Target Schemas
50
3.4
Process .................................................................................................................
and Generate Files Dynamically
59
4
Common Tasks
4.1
Working.................................................................................................................
with Mappings
71
12
32
70
4.1.1 Adding Components
...................................................................................................
to the Mapping
71
4.1.2 Adding Components
...................................................................................................
from a URL
72
4.1.3 About Data
...................................................................................................
Streaming
75
4.1.4 Selecting a...................................................................................................
Transformation Language
76
4.1.5 Validating...................................................................................................
Mappings
77
4.1.6 Validating...................................................................................................
the Mapping Output
79
4.1.7 Previewing...................................................................................................
the Output
80
4.1.8 Text View...................................................................................................
Features
81
4.1.9 Searching ...................................................................................................
in Text View
86
4.1.10 Previewing...................................................................................................
the XSLT Code
90
4.1.11 Generating...................................................................................................
XSLT Code
90
4.1.12 Previewing...................................................................................................
the XQuery Code
91
4.1.13 Working with
...................................................................................................
Multiple Mapping Windows
91
Altova MapForce 2017 Professional Edition
1
4.2
4.1.14 Changing the
...................................................................................................
Mapping Settings
93
Working.................................................................................................................
with Components
95
4.2.1 Searching ...................................................................................................
within Components
96
4.2.2 Aligning Components
................................................................................................... 97
4.2.3 Changing the
...................................................................................................
Component Settings
98
4.2.4 Duplicating...................................................................................................
Input
98
4.3
Working
.................................................................................................................
with Connections
100
4.3.1 About Mandatory
...................................................................................................
Inputs
101
4.3.2 Changing...................................................................................................
the Connection Display Preferences
102
4.3.3 Annotating
...................................................................................................
Connections
103
4.3.4 Connection
...................................................................................................
Settings
103
4.3.5 Connection
...................................................................................................
Context Menu
105
4.3.6 Connecting
...................................................................................................
Matching Children
106
4.3.7 Notifications
...................................................................................................
on Missing Parent Connections
108
4.3.8 Moving Connections
...................................................................................................
and Child Connections
109
4.3.9 Keeping ...................................................................................................
Connections After Deleting Components
112
4.3.10 Dealing with
...................................................................................................
Missing Items
114
4.4
Working
.................................................................................................................
with Mapping Projects
118
4.4.1 Opening,...................................................................................................
Searching, and Closing Projects
119
4.4.2 Creating ...................................................................................................
a New Project
119
4.4.3 Setting the
...................................................................................................
Code Generation Settings
121
4.4.4 Managing...................................................................................................
Project Folders
122
5
Designing Mappings
126
5.1
Using Relative
.................................................................................................................
and Absolute Paths
128
5.1.1 Using Relative
...................................................................................................
Paths on a Component
128
5.1.2 Setting the
...................................................................................................
Path to File-Based Databases
130
5.1.3 Fixing Broken
...................................................................................................
Path References
132
5.1.4 About Paths
...................................................................................................
in Generated Code
133
5.2
5.1.5 Copy-Paste
...................................................................................................
and Relative Paths
134
Connection
.................................................................................................................
Types
135
5.2.1 Target-driven
...................................................................................................
connections
135
5.2.2 Source-driven
...................................................................................................
connections
135
5.3
5.2.3 Copy-All...................................................................................................
Connections
143
Chained.................................................................................................................
Mappings
146
5.3.1 Example:...................................................................................................
Pass-Through Active
148
5.3.2 Example:...................................................................................................
Pass-Through Inactive
152
2
Altova MapForce 2017 Professional Edition
5.4
Processing
.................................................................................................................
Multiple Input or Output Files Dynamically
156
5.4.1 Mapping ...................................................................................................
Multiple Input Files to a Single Output File
158
5.4.2 Mapping ...................................................................................................
Multiple Input Files to Multiple Output Files
160
5.4.3 Supplying...................................................................................................
File Names as Mapping Parameters
161
5.4.4 Previewing
...................................................................................................
Multiple Output Files
161
5.4.5 Example:...................................................................................................
Split One XML File into Many
162
5.4.6 Example:...................................................................................................
Split Database Table into Many XML Files
164
5.5
Supplying
.................................................................................................................
Parameters to the Mapping
167
5.5.1 Adding Simple
...................................................................................................
Input Components
168
5.5.2 Simple Input
...................................................................................................
Component Settings
168
5.5.3 Creating ...................................................................................................
a Default Input Value
170
5.5.4 Example:...................................................................................................
Using File Names as Mapping Parameters
171
5.6
Returning
.................................................................................................................
String Values from a Mapping
174
5.6.1 Adding Simple
...................................................................................................
Output Components
175
5.6.2 Example:...................................................................................................
Previewing Function Output
176
5.7
Using Variables
................................................................................................................. 178
5.7.1 Adding Variables
................................................................................................... 180
5.7.2 Changing...................................................................................................
the Context and Scope of Variables
183
5.7.3 Example:...................................................................................................
Counting Database Table Rows
185
5.7.4 Example:...................................................................................................
Filtering and Numbering Nodes
186
5.8
5.7.5 Example:...................................................................................................
Grouping and Subgrouping Records
188
Sorting .................................................................................................................
Data
190
5.8.1 Sorting by...................................................................................................
Multiple Keys
192
5.8.2 Sorting with
...................................................................................................
Variables
193
5.9
Filters and
.................................................................................................................
Conditions
196
5.9.1 Example:...................................................................................................
Filtering Nodes
198
5.9.2 Example:...................................................................................................
Returning a Value Conditionally
200
5.10
Joining .................................................................................................................
Data
202
5.10.1 Adding Join
...................................................................................................
Conditions
204
5.10.2 Joining Three
...................................................................................................
or More Structures
207
5.11
5.10.3 Example:...................................................................................................
Join XML Structures
208
Using Value-Maps
................................................................................................................. 214
5.11.1 Passing data
...................................................................................................
through a Value-Map unchanged
217
5.11.2 Value-Map
...................................................................................................
component properties
219
5.12
Adding.................................................................................................................
Exceptions
222
5.12.1 Example:...................................................................................................
Exception on "Greater Than" Condition
223
5.12.2 Example:...................................................................................................
Exception When Node Does Not Exist
223
Altova MapForce 2017 Professional Edition
3
5.13
Parsing.................................................................................................................
and Serializing Strings
226
5.13.1 About the...................................................................................................
Parse/Serialize Component
226
5.13.2 Example:...................................................................................................
Serialize to String (XML to Database)
228
5.14
Mapping
.................................................................................................................
Node Names
234
5.14.1 Getting Access
...................................................................................................
to Node Names
235
5.14.2 Accessing
...................................................................................................
Nodes of Specific Type
242
5.14.3 Example:...................................................................................................
Map Element Names to Attribute Values
247
5.14.4 Example:...................................................................................................
Group and Filter Nodes by Name
250
5.15
Mapping
.................................................................................................................
Rules and Strategies
255
5.15.1 Changing...................................................................................................
the Processing Order of Mapping Components
259
5.15.2 Priority Context
...................................................................................................
node/item
262
5.15.3 Overriding
...................................................................................................
the Mapping Context
264
6
Debugging Mappings
270
6.1
Debugger
.................................................................................................................
Preparation
273
6.2
Debugger
.................................................................................................................
Commands
274
6.3
About the
.................................................................................................................
Debug Mode
276
6.4
Adding.................................................................................................................
and Removing Breakpoints
279
6.5
Using the
.................................................................................................................
Values Window
282
6.6
Using the
.................................................................................................................
Context Window
284
6.7
Using the
.................................................................................................................
Breakpoints Window
286
6.8
Previewing
.................................................................................................................
Partially Generated Output
288
6.9
Viewing.................................................................................................................
the Current Value of a Connector
289
6.10
Stepping
.................................................................................................................
back into Recent Past
290
6.11
Viewing.................................................................................................................
the History of Values Processed by a Connector
291
6.12
Setting .................................................................................................................
the Context to a Value
292
6.13
Debugger
.................................................................................................................
Settings
293
7
Data Sources and Targets
7.1
XML and
.................................................................................................................
XML schema
297
296
7.1.1 Generating
...................................................................................................
an XML Schema
297
7.1.2 XML Component
...................................................................................................
Settings
297
7.1.3 Using DTDs
...................................................................................................
as "Schema" Components
301
7.1.4 Derived XML
...................................................................................................
Schema Types
302
7.1.5 QNames................................................................................................... 304
7.1.6 Nil Values
...................................................................................................
/ Nillable
304
4
Altova MapForce 2017 Professional Edition
7.1.7 Comments
...................................................................................................
and Processing Instructions
308
7.1.8 CDATA...................................................................................................
Sections
309
7.1.9 Wildcards...................................................................................................
- xs:any / xs:anyAttribute
310
7.1.10 Merging ...................................................................................................
Data from Multiple Schemas
314
7.2
7.1.11 Declaring...................................................................................................
Custom Namespaces
316
Databases
.................................................................................................................
and MapForce
319
7.2.1 Connecting
...................................................................................................
to a Database
321
7.2.2 Introduction
...................................................................................................
to Database Mappings
396
7.2.3 Mapping ...................................................................................................
Data to Databases
426
7.2.4 Joining Database
...................................................................................................
Data
473
7.2.5 Filtering and
...................................................................................................
Sorting Database Data (SQL WHERE/ORDER)
488
7.2.6 SQL SELECT
...................................................................................................
Statements as Virtual Tables
494
7.2.7 Mapping ...................................................................................................
XML Data to / from Database Fields
504
7.2.8 Browsing...................................................................................................
and Querying Databases
514
7.3
7.2.9 Stored Procedures
................................................................................................... 532
CSV and
.................................................................................................................
Text Files
555
7.3.1 Example:...................................................................................................
Mapping CSV Files to XML
555
7.3.2 Example:...................................................................................................
Iterating Through Items
557
7.3.3 Example:...................................................................................................
Creating Hierarchies from CSV and Fixed-Length Text Files
560
7.3.4 Setting the
...................................................................................................
CSV Options
563
7.3.5 Example:...................................................................................................
Mapping Fixed-Length Text Files to Databases
567
7.3.6 Setting the
...................................................................................................
FLF Options
574
7.4
HL7 Version
.................................................................................................................
3
581
8
Functions
8.1
Working
.................................................................................................................
with Functions
585
8.2
User-Defined
.................................................................................................................
Functions
588
584
8.2.1 Function ...................................................................................................
parameters
593
8.2.2 Inline and...................................................................................................
regular user-defined functions
596
8.2.3 Creating ...................................................................................................
a simple look-up function
597
8.2.4 User-defined
...................................................................................................
function - example
601
8.2.5 Complex...................................................................................................
user-defined function - XML node as input
606
8.2.6 Complex...................................................................................................
user-defined function - XML node as output
612
8.3
8.2.7 Recursive...................................................................................................
user-defined mapping
616
Importing
.................................................................................................................
Custom XSLT 1.0 or 2.0 Functions
626
8.3.1 Example:...................................................................................................
Adding Custom XSLT Functions
627
8.3.2 Example:...................................................................................................
Summing Node Values
630
Altova MapForce 2017 Professional Edition
5
8.4
Importing
.................................................................................................................
Custom XQuery 1.0 Functions
633
8.5
Importing
.................................................................................................................
Custom Java and .NET Libraries
634
8.5.1 Example:...................................................................................................
Import Custom Java Class
636
8.5.2 Example:...................................................................................................
Import Custom .NET DLL Assembly
637
8.6
Referencing
.................................................................................................................
Java, C# and C++ Libraries Manually
639
8.6.1 Configuring
...................................................................................................
the .mff File
639
8.6.2 Importing...................................................................................................
the .mff File Into MapForce
645
8.6.3 Data Type
...................................................................................................
Mapping
645
8.6.4 Example:...................................................................................................
Create a Custom C# Library
648
8.6.5 Example:...................................................................................................
Create a Custom C++ Library
649
8.6.6 Example:...................................................................................................
Create a Custom Java Library
652
8.7
Regular.................................................................................................................
Expressions
654
8.8
Function
.................................................................................................................
Library Reference
657
8.8.1 core | aggregate
...................................................................................................
functions
657
8.8.2 core | conversion
...................................................................................................
functions
662
8.8.3 core | file...................................................................................................
path functions
672
8.8.4 core | generator
...................................................................................................
functions
675
8.8.5 core | logical
...................................................................................................
functions
677
8.8.6 core | math
...................................................................................................
functions
680
8.8.7 core | node
...................................................................................................
functions
683
8.8.8 core | QName
...................................................................................................
functions
686
8.8.9 core | sequence
...................................................................................................
functions
686
8.8.10 core | string
...................................................................................................
functions
701
8.8.11 db
................................................................................................... 709
8.8.12 lang | QName
...................................................................................................
functions
711
8.8.13 lang | datetime
...................................................................................................
functions
711
8.8.14 lang | generator
...................................................................................................
functions
724
8.8.15 lang | logical
...................................................................................................
functions
724
8.8.16 lang | math
...................................................................................................
functions
725
8.8.17 lang | string
...................................................................................................
functions
729
8.8.18 xpath2 | accessors
................................................................................................... 734
8.8.19 xpath2 | anyURI
...................................................................................................
functions
734
8.8.20 xpath2 | boolean
...................................................................................................
functions
735
8.8.21 xpath2 | constructors
................................................................................................... 735
8.8.22 xpath2 | context
...................................................................................................
functions
736
8.8.23 xpath2 | durations,
...................................................................................................
date and time functions
738
8.8.24 xpath2 | node
...................................................................................................
functions
740
6
Altova MapForce 2017 Professional Edition
8.8.25 xpath2 | numeric
...................................................................................................
functions
741
8.8.26 xpath2 | string
...................................................................................................
functions
741
8.8.27 xslt | xpath
...................................................................................................
functions
743
8.8.28 xslt | xslt ...................................................................................................
functions
746
9
Automating Mappings and MapForce
9.1
About MapForce
.................................................................................................................
Server
751
9.2
Compiling
.................................................................................................................
Mappings to MapForce Server Execution Files
752
9.3
Deploying
.................................................................................................................
Mappings to FlowForce Server
754
9.4
Automation
.................................................................................................................
with RaptorXML Server
759
9.5
MapForce
.................................................................................................................
Command Line Interface
760
10 Customizing MapForce
750
766
10.1
Changing
.................................................................................................................
the MapForce Options
767
10.2
Altova .................................................................................................................
Global Resources
769
10.2.1 Global Resources
...................................................................................................
- Files
769
10.2.2 Global Resources
...................................................................................................
- Folders
775
10.2.3 Global Resources
...................................................................................................
- Application workflow
777
10.2.4 Global Resources
...................................................................................................
- Databases
785
10.3
10.2.5 Global Resources
...................................................................................................
- Properties
790
Styling .................................................................................................................
Mapping Output with StyleVision
794
10.4
10.3.1 Examples...................................................................................................
of Mappings with StyleVision Stylesheets
795
Generating
.................................................................................................................
and Customizing Mapping Documentation
798
10.4.1 Predefined
...................................................................................................
StyleVision Power Stylesheets
803
10.4.2 Custom Design
................................................................................................... 806
10.5
Customizing
.................................................................................................................
Keyboard Shortcuts
808
10.6
Catalog.................................................................................................................
Files
810
11 MapForce Plug-in for Visual Studio
816
11.1
Enabling
.................................................................................................................
the Plug-in
817
11.2
Working
.................................................................................................................
with Mappings and Projects
819
11.3
Accessing
.................................................................................................................
Common Menus and Functions
821
12 MapForce Plug-in for Eclipse
12.1
824
Installing
.................................................................................................................
the MapForce Plug-in for Eclipse
825
Altova MapForce 2017 Professional Edition
7
12.2
The MapForce
.................................................................................................................
Perspective
830
12.3
Accessing
.................................................................................................................
Common Menus and Functions
833
12.4
Working
.................................................................................................................
with Mappings and Projects
836
12.4.1 Creating ...................................................................................................
a MapForce/Eclipse Project
836
12.4.2 Creating ...................................................................................................
New Mappings
838
12.4.3 Importing...................................................................................................
Existing Mappings into an Eclipse Project
840
12.4.4 Configuring
...................................................................................................
Automatic Build and Generation of MapForce Code
843
12.5
Extending
.................................................................................................................
MapForce Plug-in for Eclipse
846
13 Menu Reference
852
13.1
File
................................................................................................................. 853
13.2
Edit
................................................................................................................. 856
13.3
Insert ................................................................................................................. 857
13.4
Project................................................................................................................. 859
13.5
Component
................................................................................................................. 860
13.6
Connection
................................................................................................................. 861
13.7
Function
................................................................................................................. 862
13.8
Output ................................................................................................................. 863
13.9
Debug ................................................................................................................. 864
13.10 View ................................................................................................................. 865
13.11 Tools ................................................................................................................. 867
13.12 Window................................................................................................................. 868
13.13 Help Menu
................................................................................................................. 869
14 Code Generator
876
14.1
Introduction
.................................................................................................................
to code generator
877
14.2
What's .................................................................................................................
new ...
879
14.3
Generating
.................................................................................................................
C++ code
881
14.3.1 Generating
...................................................................................................
code from a mapping
882
14.3.2 Generating
...................................................................................................
code from a mapping project
882
14.3.3 Building the
...................................................................................................
project
883
14.3.4 Running the
...................................................................................................
application
884
14.4
Generating
.................................................................................................................
C# code
885
14.4.1 Generating
...................................................................................................
code from a mapping
886
14.4.2 Generating
...................................................................................................
code from a mapping project
886
14.4.3 Building the
...................................................................................................
project
887
8
Altova MapForce 2017 Professional Edition
14.5
14.4.4 Running the
...................................................................................................
application
887
Generating
.................................................................................................................
Java code
888
14.5.1 Generating
...................................................................................................
code from a mapping
889
14.5.2 Generating
...................................................................................................
code from a mapping project
890
14.5.3 Handling...................................................................................................
JDBC references
890
14.5.4 Building the
...................................................................................................
project with Ant
891
14.6
14.5.5 Example:...................................................................................................
Build a Java application with Eclipse and Ant
892
Integrating
.................................................................................................................
MapForce-Generated Code
902
14.6.1 Java example
................................................................................................... 903
14.6.2 C# example
................................................................................................... 905
14.6.3 C++ example
................................................................................................... 907
14.6.4 Changing...................................................................................................
the data type of the mapping input/output (C#, Java)
908
14.7
Generating
.................................................................................................................
Code from XML Schemas or DTDs
913
14.7.1 About Schema
...................................................................................................
Wrapper Libraries (C++)
915
14.7.2 About Schema
...................................................................................................
Wrapper Libraries (C#)
918
14.7.3 About Schema
...................................................................................................
Wrapper Libraries (Java)
921
14.7.4 Integrating
...................................................................................................
Schema Wrapper Libraries
923
14.8
14.7.5 Example:...................................................................................................
Using the Schema Wrapper Libraries
926
Reference
.................................................................................................................
to Generated Classes (C++)
950
14.8.1 altova::DateTime
................................................................................................... 950
14.8.2 altova::Duration
................................................................................................... 953
14.8.3 altova::DayTimeDuration
................................................................................................... 955
14.8.4 altova::YearMonthDuration
................................................................................................... 956
14.8.5 altova::meta::Attribute
................................................................................................... 957
14.8.6 altova::meta::ComplexType
................................................................................................... 958
14.8.7 altova::meta::Element
................................................................................................... 959
14.8.8 altova::meta::SimpleType
................................................................................................... 959
14.8.9 [YourSchema]::[CDoc]
................................................................................................... 961
14.8.10 [YourSchema]::MemberAttribute
................................................................................................... 963
14.8.11 [YourSchema]::MemberElement
................................................................................................... 964
14.9
Reference
.................................................................................................................
to Generated Classes (C#)
966
14.9.1 Altova.Types.DateTime
................................................................................................... 966
14.9.2 Altova.Types.DateTimeFormat
................................................................................................... 970
14.9.3 Altova.Types.Duration
................................................................................................... 971
14.9.4 Altova.Xml.Meta.Attribute
................................................................................................... 974
14.9.5 Altova.Xml.Meta.ComplexType
................................................................................................... 974
14.9.6 Altova.Xml.Meta.Element
................................................................................................... 975
Altova MapForce 2017 Professional Edition
9
14.9.7 Altova.Xml.Meta.SimpleType
................................................................................................... 976
14.9.8 [YourSchema].[Doc]
................................................................................................... 976
14.9.9 [YourSchemaType].MemberAttribute
................................................................................................... 978
14.9.10 [YourSchemaType].MemberElement
................................................................................................... 979
14.10 Reference
.................................................................................................................
to Generated Classes (Java)
981
14.10.1 com.altova.types.DateTime
................................................................................................... 981
14.10.2 com.altova.types.Duration
................................................................................................... 986
14.10.3 com.altova.xml.meta.Attribute
................................................................................................... 989
14.10.4 com.altova.xml.meta.ComplexType
................................................................................................... 990
14.10.5 com.altova.xml.meta.Element
................................................................................................... 991
14.10.6 com.altova.xml.meta.SimpleType
................................................................................................... 991
14.10.7 com.[YourSchema].[Doc]
................................................................................................... 992
14.10.8 com.[YourSchema].[YourSchemaType].MemberAttribute
................................................................................................... 994
14.10.9 com.[YourSchema].[YourSchemaType].MemberElement
................................................................................................... 995
14.11 Code Generation
.................................................................................................................
Tips
997
14.12 Code Generator
.................................................................................................................
Options
998
14.13 SPL (Spy
.................................................................................................................
Programming Language)
999
14.13.1 Basic SPL
...................................................................................................
structure
999
14.13.2 Declarations
................................................................................................... 1000
14.13.3 Variables
................................................................................................... 1001
14.13.4 Predefined
...................................................................................................
variables
1002
14.13.5 Creating...................................................................................................
output files
1003
14.13.6 Operators
................................................................................................... 1004
14.13.7 Conditions
................................................................................................... 1005
14.13.8 Collections
...................................................................................................
and foreach
1006
14.13.9 Subroutines
................................................................................................... 1007
14.13.10Built in Types
................................................................................................... 1010
15 The MapForce API
15.1
1016
Overview
................................................................................................................. 1017
15.1.1 Accessing
...................................................................................................
the API
1017
15.1.2 The Object
...................................................................................................
Model
1019
15.1.3 Error Handling
................................................................................................... 1020
15.1.4 Examples
................................................................................................... 1021
15.2
Object.................................................................................................................
Reference
1045
15.2.1 Application
................................................................................................... 1045
15.2.2 AppOutputLine
................................................................................................... 1054
10
Altova MapForce 2017 Professional Edition
15.2.3 AppOutputLines
................................................................................................... 1059
15.2.4 AppOutputLineSymbol
................................................................................................... 1060
15.2.5 Component
................................................................................................... 1061
15.2.6 Components
................................................................................................... 1069
15.2.7 Connection
................................................................................................... 1070
15.2.8 Datapoint
................................................................................................... 1071
15.2.9 Document
................................................................................................... 1072
15.2.10 Documents
................................................................................................... 1082
15.2.11 ErrorMarker
................................................................................................... 1084
15.2.12 ErrorMarkers
................................................................................................... 1086
15.2.13 MapForceView
................................................................................................... 1087
15.2.14 Mapping................................................................................................... 1092
15.2.15 Mappings
................................................................................................... 1097
15.2.16 Options................................................................................................... 1098
15.2.17 Project ................................................................................................... 1103
15.2.18 ProjectItem
................................................................................................... 1112
15.3
Enumerations
................................................................................................................. 1121
15.3.1 ENUMApacheAxisVersion
...................................................................................................
(obsolete)
1121
15.3.2 ENUMApplicationStatus
................................................................................................... 1121
15.3.3 ENUMAppOutputLine_Severity
................................................................................................... 1121
15.3.4 ENUMAppOutputLine_TextDecoration
................................................................................................... 1122
15.3.5 ENUMCodeGenErrorLevel
................................................................................................... 1122
15.3.6 ENUMComponentDatapointSide
................................................................................................... 1122
15.3.7 ENUMComponentSubType
................................................................................................... 1123
15.3.8 ENUMComponentType
................................................................................................... 1123
15.3.9 ENUMComponentUsageKind
................................................................................................... 1123
15.3.10 ENUMConnectionType
................................................................................................... 1123
15.3.11 ENUMDOMType
................................................................................................... 1124
15.3.12 ENUMLibType
................................................................................................... 1124
15.3.13 ENUMProgrammingLanguage
................................................................................................... 1124
15.3.14 ENUMProjectItemType
................................................................................................... 1125
15.3.15 ENUMProjectType
................................................................................................... 1125
15.3.16 ENUMSearchDatapointFlags
................................................................................................... 1125
15.3.17 ENUMViewMode
................................................................................................... 1126
16 ActiveX Integration
16.1
1128
Prerequisites
................................................................................................................. 1129
Altova MapForce 2017 Professional Edition
11
16.2
Adding.................................................................................................................
the ActiveX Controls to the Toolbox
1131
16.3
Integration
.................................................................................................................
at Application Level
1133
16.4
Integration
.................................................................................................................
at Document Level
1136
16.5
ActiveX
.................................................................................................................
Integration Examples
1140
16.5.1 C#
................................................................................................... 1140
16.5.2 HTML ................................................................................................... 1147
16.5.3 Java ................................................................................................... 1154
16.5.4 VB.NET
................................................................................................... 1164
16.6
Command
.................................................................................................................
Reference
1167
16.6.1 "File" Menu
................................................................................................... 1167
16.6.2 "Edit" Menu
................................................................................................... 1168
16.6.3 "Insert"...................................................................................................
Menu
1169
16.6.4 "Project"
...................................................................................................
Menu
1169
16.6.5 "Component"
...................................................................................................
Menu
1170
16.6.6 "Connection"
...................................................................................................
Menu
1172
16.6.7 "Function"
...................................................................................................
Menu
1172
16.6.8 "Output"...................................................................................................
Menu
1172
16.6.9 "Debug"...................................................................................................
Menu
1173
16.6.10 "View" ...................................................................................................
Menu
1174
16.6.11 "Tools" ...................................................................................................
Menu
1174
16.6.12 "Window"
...................................................................................................
Menu
1175
16.6.13 "Help" Menu
................................................................................................... 1175
16.7
Object.................................................................................................................
Reference
1177
16.7.1 MapForceCommand
................................................................................................... 1177
16.7.2 MapForceCommands
................................................................................................... 1179
16.7.3 MapForceControl
................................................................................................... 1180
16.7.4 MapForceControlDocument
................................................................................................... 1188
16.7.5 MapForceControlPlaceHolder
................................................................................................... 1194
16.7.6 Enumerations
................................................................................................... 1197
17 Appendices
17.1
1200
Engine.................................................................................................................
information
1201
17.1.1 XSLT and
...................................................................................................
XQuery Engine Information
1201
17.1.2 XSLT and
...................................................................................................
XPath/XQuery Functions
1207
17.2
Technical
.................................................................................................................
Data
1274
17.2.1 OS and ...................................................................................................
Memory Requirements
1274
17.2.2 Altova XML
...................................................................................................
Validator
1274
12
Altova MapForce 2017 Professional Edition
17.2.3 Altova XSLT
...................................................................................................
and XQuery Engines
1275
17.2.4 Unicode...................................................................................................
Support
1275
17.3
17.2.5 Internet...................................................................................................
Usage
1275
License
.................................................................................................................
Information
1277
17.3.1 Electronic
...................................................................................................
Software Distribution
1277
17.3.2 Software
...................................................................................................
Activation and License Metering
1278
17.3.3 Intellectual
...................................................................................................
Property Rights
1279
17.3.4 Altova End
...................................................................................................
User License Agreement
1279
18 Glossary
1294
18.1
C
................................................................................................................. 1295
18.2
F
................................................................................................................. 1296
18.3
I
................................................................................................................. 1297
18.4
J
................................................................................................................. 1298
18.5
M
................................................................................................................. 1299
18.6
O
................................................................................................................. 1300
18.7
P
................................................................................................................. 1301
18.8
S
................................................................................................................. 1302
18.9
T
................................................................................................................. 1303
Index
Altova MapForce 2017 Professional Edition
13
Chapter 1
Altova MapForce 2017 Professional Edition
Altova MapForce 2017 Professional Edition
1
3
Altova MapForce 2017 Professional Edition
MapForce® 2017 Professional Edition is a visual data mapping tool for advanced data
integration projects. MapForce® is a 32/64-bit Windows application that runs on Windows 10,
Windows 8, Windows 7, Windows Vista, Windows XP, and Windows Server 2003/2008/2012. 64bit support is available for the Enterprise and Professional editions.
Last updated: 31 March 2017
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
4
1.1
Altova MapForce 2017 Professional Edition
What's new...
What's new...
New in MapForce 2017 Release 3:
A new component type (Join) has been introduced which can be used to join data from
two or more different structures based on custom-defined conditions (see Joining Data).
When the mapping reads data from a database, it is possible to join database tables or
views in SQL JOIN mode, see Joining Database Data.
The text search options in the Output pane, the XQuery pane, as well as the XSLT
pane have been enhanced (see Searching in Text View). Also, text highlighting is
available in the above-mentioned panes (see Text Highlighting).
Mappings which update databases can be optionally configured to compare data in a
NULL-aware manner. NULL-aware comparisons provide a better way (tailored to each
specific database) to handle data that contains null values (see Handling Nulls in
Database Table Actions).
In the MapForce ActiveX control, the structure of the MapForceCommand object has been
enhanced to include a new Name property, which can be used to get the unique name of
the command. This simplifies retrieving information about MapForce commands
programmatically (see Retrieving Command Information).
Internal updates and optimizations
New in MapForce 2017:
It is possible to read node names from a source XML (or field names from a CSV/Fixedlength field file) and map this information to a target. It is also possible to dynamically
create new XML attributes or elements in a target based on values supplied from a
source. See Mapping Node Names.
XML instance files can be created with custom namespaces, at element level (see
Declaring Custom Namespaces)
MapForce Server execution files (.mfx) can be compiled for specific MapForce Server
versions (see Compiling mappings for a specific MapForce Server version)
Mappings can connect to PostgreSQL databases through native connections (see
Setting up a PostgreSQL Connection)
Mappings can connect to SQL Server and other database types through ADO.NET
providers (see Setting up an ADO.NET Connection)
A new database type is supported: Progress OpenEdge. See Connecting to Progress
OpenEdge (ODBC) and Connecting to Progress OpenEdge (JDBC).
When connecting to a database through JDBC, the search path to .jar libraries can be
specified directly in the database connection dialog box (see Setting up a JDBC
Connection)
When a database is updated by the mapping through "Update if... Insert Rest" actions,
MERGE statements are created for selected databases (see MERGE statements)
Internal updates and optimizations
New in MapForce 2016 R2:
More intuitive code folding in the XSLT pane: collapsed text is displayed with an ellipsis
symbol and can be previewed as a tooltip. The same rules apply for text in the XQuery
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
What's new...
5
pane and the SQL Editor
You can search for all occurrences of a function within the active mapping (in the Libraries
window, right-click the function, and select Find All Calls).
Internal updates and optimizations
New features in MapForce 2016:
Improved generation of XSLT 1.0 code (generated stylesheets are easier to read and often
faster to execute)
Two new aggregate functions are available in the MapForce core library: min-string and
max-string. These functions enable you to get the minimum or maximum value from a
sequence of strings.
Mappings written for the Built-in execution engine can be debugged (see Debugging
Mappings)
The MapForce Plug-in for Visual Studio supports Visual Studio 2015 (adds to support for
previous versions)
New database versions are supported: SQL Server 2014, Oracle 12c, IBM DB2 10.5,
PostgreSQL 9.4, MySQL 5.6 (adds to support for previous versions)
Firebird databases are supported (see Connecting to Firebird (ODBC) and Connecting to
Firebird (JDBC) )
New features in MapForce Version 2015 R4:
In the MapForce plug-in for Eclipse, the commands specific to MapForce files are now
available under a new MapForce menu (see Accessing Common Menus and Functions)
Internal updates and optimizations
New features in MapForce Version 2015 R3 include:
Option to suppress the <?xml ... ?> declaration in XML output
Text-based components (including EDI, CSV, fixed-length field, JSON, and XML) can
parse and serialize strings in addition to plain files
SQLite database support (see Setting up a SQLite connection)
New string padding functions: pad-string-left and pad-string-right
New component type: Simple Output
Internal updates and optimizations
New features in MapForce Version 2015 include:
New language argument available in the format-date and format-dateTime functions
New sequence function: replicate-item
New features in MapForce Version 2014 R2 include:
New sequence functions: generate sequence, item-at, etc.
Ability to define CDATA sections in output components
Ability to define timeout values for database execution
Keeping connections after deleting components
Bulk transfer of database data (bulk Insert all)
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
6
Altova MapForce 2017 Professional Edition
What's new...
Automatic highlighting of mandatory items in target components
New features in MapForce Version 2014 include:
Integration of RaptorXML validator and basic support for XML Schema 1.1
Integration of new RaptorXML XSLT and XQuery engines
XML Schema Wildcard support, xs:any and xs:anyAttribute
Support for Comments and Processing Instructions in XML target components
Age function
Ability to always insert quote character for CSV files
New features in MapForce Version 2013 R2 SP1 include:
New super-fast transformation engine RaptorXML Server
New features in MapForce Version 2013 R2 include:
MapForce Server support.
Ability to generate a MapForce Server execution file from the command line and File
menu, to be executed by MapForce Server.
Ability to deploy MapForce mappings to FlowForce Server.
Support for Informix 11.7 databases, and extended support for other databases.
User defined end-of-line settings for output files.
Internal updates and optimizations.
New features in MapForce Version 2013 include:
Ability to call stored procedures in mappings
Support for database functions (functionally similar to stored procedures)
Support for SELECT statements with parameters
Internal updates and optimizations
New features in MapForce Version 2012 R2 include:
New Sort component for XSLT 2.0, XQuery, and the Built-in execution engine
User defined component names
Extended SQL-Where functionality: ORDER BY
MapForce supports logical files of the IBM iSeries database and shows logical files as
views
Support for IBM DB2 logical files. A logical file in IBM iSeries editions of the DB2
database represents one or more physical files. A logical file allows users to access data
in a sequence or format that can be different from the physical file. Users who connect to
IBM iSeries computers may encounter existing databases constructed with logical files.
These were previously not accessible, but are now supported in Version 2012 Release 2.
New features in MapForce Version 2012 include:
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
What's new...
7
Data streaming for XML, CSV and fixed-length field files (when using the built-in execution
engine)
New database engine supports direct ODBC and JDBC connections
Auto-alignment of components in the mapping window
New functions: parse-date and parse-time
Find items in Project tab/window
Prompt to connect to target parent node
Specific rules governing the sequence that components are processed in a mapping
New Programming Languages examples section in MapForce API
New features in MapForce Version 2011R3 include:
Intermediate variablesSupport for .NET Framework 4.0 assembly files
Ability to output StyleVision formatted documents from the command line
New features in MapForce Version 2011R2 include:
Built-in Execution Engine now supports streaming output
Find function capability in Library window
Reverse mapping
Extendable IF-ELSE function
Node Name and parsing functions in Core LibraryImproved database table actions dialog
with integrated key generation settings
New option of using StyleVision Power Stylesheets when documenting a mapping
New features in MapForce Version 2011 include:
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
Ability to preview target components using StyleVision Power Stylesheets containing
StyleVision Charts
New features in MapForce Version 2010 Release 3 include:
Support for generation of Visual Studio 2010 project files for C# and C++ added
Support for MSXML 6.0 in generated C++ code
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:
64-bit MapForce Enterprise / Professional editions on 64-bit operating systems: Windows
Server 2003/2008, Windows XP, Windows Vista and Windows 7Automatic connection of
identical child connections when moving a parent connection
Support for fields in the SQL Where component
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
8
Altova MapForce 2017 Professional Edition
What's new...
Ability to add compiled Java .class and .NET assembly files
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
Apache Xerces 3.x support when generating C++ code
New features in MapForce Version 2009 include:
EDI HL7 versions 3.x XML as source and target components
Documentation of mapping projects
Native support for XML fields in SQL Server
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 stream objects as input/output in generated Java and C# code
Generation of Visual Studio 2008 project files for C++ and C#
Ability to strip database schema names from generated code
SQL SELECT Statements as virtual tables in database components
Local Relations - on-the-fly creation of primary/foreign key relationships
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
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
What's new...
9
New features in MapForce Version 2007 Release 3 include:
XML data mapping to/from database fields (see Mapping XML Data to / from Database
Fields )
Direct querying of databases
SQL-WHERE filter and SQL statement wizard
Code generator optimization and improved documentation
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
Chapter 2
Introduction
12
Introduction
2
Introduction
This introduction includes an overview of the MapForce features and user interface, the basic
concepts in MapForce, as well as the conventions used in this documentation.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Introduction
2.1
What Is MapForce?
13
What Is MapForce?
MapForce is a Windows-based, multi-purpose IDE (integrated development environment) that
enables you to transform data from one format to another, or from one schema to another, by
means of a visual, "drag-and-drop" -style graphical user interface that does not require writing any
program code. In fact, MapForce generates for you the program code which performs the actual
data transformation (or data mapping). When you prefer not to generate program code, you can
just run the transformation using the MapForce built-in transformation language (available in the
MapForce Professional or Enterprise Editions).
You can use MapForce to conveniently convert and transform data from and to a variety of filebased and other formats. Regardless of the technology you work with, MapForce determines
automatically the structure of your data, or gives you the option to supply a schema for your data,
or generate it automatically from a sample instance file. For example, if you have an XML instance
file but no schema definition, MapForce can generate it for you, thus making the data inside the
XML file available for mapping to other files or formats.
The technologies supported as mapping sources or targets are as follows.
MapForce Basic Edition
XML and XML schema
HL7 version 3.x (schemabased)
MapForce Professional
Edition
MapForce Enterprise Edition
XML and XML schema
Flat files, including commaseparated values (CSV) and
fixed-length field (FLF)
format
Databases (all major
relational databases,
including Microsoft Access
and SQLite databases)
XML and XML schema
Flat files, including commaseparated values (CSV) and
fixed-length field (FLF)
format
Data from legacy text files
can be mapped and
converted to other formats
with MapForce FlexText
Databases (all major
relational databases,
including Microsoft Access
and SQLite databases)
EDI family of formats
(including UN/EDIFACT,
ANSI X12, HL7, IATA
PADIS, SAP IDoc,
TRADACOMS)
JSON files
Microsoft Excel 2007 and
later files
XBRL instance files and
taxonomies
Based on the MapForce edition, you can choose the preferred language for your data
transformation as follows.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
14
Introduction
MapForce Basic Edition
XSLT 1.0
XSLT 2.0
What Is MapForce?
MapForce Professional
Edition
MapForce built-In
transformation language
XSLT 1.0
XSLT 2.0
XQuery
Java
C#
C++
MapForce Enterprise Edition
MapForce built-In
transformation language
XSLT 1.0
XSLT 2.0
XQuery
Java
C#
C++
You can preview the result of all transformations, as well as the generated XSLT or XQuery code
without leaving the graphical user interface. Note that, as you design or preview mappings,
MapForce validates the integrity of your schemas or transformations and displays any validation
errors in a dedicated window, so that you can immediately review and address them.
When you choose Java, C#, or C++ as transformation language, MapForce generates the required
projects and solutions so that you can open them directly in Visual Studio or Eclipse, and run the
generated data mapping program. For advanced data integration scenarios, you can also extend
the generated program with your own code, using Altova libraries and the MapForce API.
In MapForce, you design all mapping transformations visually. For example, in case of XML, you
can connect any element, attribute, or comment in an XML file to an element or attribute of
another XML file, thus instructing MapForce to read data from the source element (or attribute),
and write it to the target element (or attribute).
Sample data transformation b etween two XML files
Likewise, when working with databases in MapForce Professional or Enterprise Editions, you can
see any database column in the MapForce mapping area and map data to or from it by making
visual connections. As with other Altova MissionKit products, when setting up a database
connection from MapForce, you can flexibly choose the database driver and the connection type
(ADO, ODBC, or JDBC) according to your existing infrastructure and data mapping needs.
Additionally, you can visually build SQL queries, use stored procedures, or query a database
directly (support varies by database type, edition and driver).
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Introduction
What Is MapForce?
15
Sample data transformation b etween an XML file and a datab ase
In a very simple scenario, a mapping design created with MapForce could be resumed as "read
data from the source X and write it to target Y". However, you can easily design MapForce
scenarios such as "read data from the source X and write it to target Y, and then read data from
the source Y and write it to the target Z". These are known as "pass-through", or "chained"
mappings, and enable you to access your data at an intermediary stage in the transformation
process (in order to save it to a file, for example).
Note that the data mappings you can create in MapForce are not limited to single, predefined
files. In the same transformation, you can process dynamically multiple input files from a directory
and generate multiple output files. Therefore, you can have scenarios such as "read data from
multiple X files and write it to a single Y file", or "read file X and generate multiple files Y", and so
on.
Importantly, in the same transformation, you can mix multiple sources and multiple targets, which
can be of any type supported by your MapForce edition. For example, in case of MapForce
Professional or Enterprise, this makes it possible to merge data from two different databases into
a single XML file. Or, you can merge data from multiple XML files, and write some of the data to
one database, and some of the data to another database. You can preview the SQL statements
before committing them to the database.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
16
Introduction
What Is MapForce?
Direct conversion of data from a source to a target is not typically the only thing you want to
achieve. In many cases, you might want to process your data in a particular way (for example,
sort, group or filter it) before it reaches the destination. For this reason, MapForce includes, on
one hand, miscellaneous functional components that are simplified programming language
constructs (such as constants, variables, SQL-WHERE conditions, Filter and Sort components).
On the other hand, MapForce includes rich and extensible function libraries which can assist you
with virtually any kind of data manipulation.
If necessary, you can extend the built-in library either with functions you design in MapForce
directly (the so-called User-Defined Functions, or UDF), or with functions or libraries created
externally in XSLT, XQuery, Java, or C# languages.
Lib raries pane (MapForce Basic Edition)
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Introduction
What Is MapForce?
17
When your data mapping design files become too many, you can organize them into mapping
projects (available in MapForce Professional and Enterprise edition). This allows for easier access
and management. Importantly, you can generate program code from entire projects, in addition to
generating code for individual mappings within the project.
For advanced data processing needs (such as when running mapping transformations with the
MapForce Server API), you can design a mapping so that you can pass values to it at run-time, or
get a simple string value from it at run-time. This feature also enables you to quickly test the
output of functions or entire mappings that produce a simple string value. The Professional and
Enterprise editions of MapForce also include components that enable you to perform run-time
string parsing and serialization, similar to how this works in many other programming languages.
With MapForce Enterprise Edition, you can visually design SOAP 1.0 and SOAP 2.0 Web
services based on Web Service Language Definition (WSDL) files. You can also call and get data
from a WSDL 1.0 or a WSDL 2.0 Web service from within a mapping. This includes Web services
available both through the HTTP and HTTPS protocols, as well as Web services which require that
the caller uses the WS-Security mechanism, or HTTP authentication.
With MapForce Professional and Enterprise Editions, you can generate detailed documentation of
your mapping design files, in HTML, Word 2007+, or RTF formats. Documentation design can be
customized (for example, you can choose to include or exclude specific components from the
documentation).
If you are using MapForce alongside other Altova MissionKit products, MapForce integrates with
them as well as with the Altova server-based products, as shown in the following table.
MapForce Basic Edition
MapForce Professional
Edition
MapForce Enterprise Edition
You can choose to run the generated XSLT directly in MapForce and preview the data
transformation result immediately. When you need increased performance, you can process
the mapping using RaptorXML Server, an ultra-fast XML transformation engine.
If XMLSpy is installed on the same machine, you can conveniently open and edit any supported
file types, by opening XMLSpy directly from the relevant MapForce contexts (for example, the
Component | Edit Schema Definition in XMLSpy menu command is available when you
click an XML component).
You can run data transformations either directly in MapForce,
or deploy them to a different machine and even operating
system for command-line or automated execution. More
specifically, you can design mappings on Windows, and run
them on a Windows, Linux, or Mac server machine which runs
MapForce Server or FlowForce Server.
If StyleVision is installed on the same machine, you can
design or reuse existing StyleVision Power Stylesheets and
preview the result of the mapping transformations as HTML,
RTF, PDF, or Word 2007+ documents.
MapForce Professional and Enterprise edition can be installed as a plug-in of Visual Studio and
Eclipse integrated development environments. This way, you can design mappings and get
access to MapForce functionality without leaving your preferred development environment.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
18
Introduction
What Is MapForce?
In MapForce, you can completely customize not only the look and feel of the development
environment (graphical user interface), but also various other settings pertaining to each
technology and to each mapping component type, for example:
When mapping to or from XML, you can choose whether to include a schema reference,
or whether the XML declaration must be suppressed in the output XML files. You can also
choose the encoding of the generated files (for example, UTF-8).
When mapping to or from databases, you can define settings such as the time-out period
for executing database statements, whether MapForce should use database
transactions, or whether it should strip the database schema name from table names
when generating code.
In case of XBRL, you can select the structure views MapForce should display (such as
the "Presentation and definition linkbases" view, the "Table Linkbase" View, or the "All
concepts" view).
All editions of MapForce are available as a 32-bit application. The MapForce Professional and
Enterprise editions are additionally available as a 64-bit application.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Introduction
2.2
Basic Concepts
19
Basic Concepts
This section outlines the basic concepts that will help you get started with data mapping.
Mapping
A MapForce mapping design (or simply "mapping") is the visual representation of how data is to
be transformed from one format to another. A mapping consists of components that you add to
the MapForce mapping area in order to create your data transformations (for example, convert
XML documents from one schema to another). A valid mapping consists of one or several source
components connected to one or several target components. You can run a mapping and preview
its result directly in MapForce. You can generate code and execute it externally. You can also
compile a mapping to a MapForce execution file and automate mapping execution using
MapForce Server or FlowForce Server. MapForce saves mappings as files with .mfd extension.
Basic structure of a MapForce mapping
Component
In MapForce, the term "component" is what represents visually the structure (schema) of your
data, or how data is to be transformed (functions). Components are the central building pieces of
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
20
Introduction
Basic Concepts
any mapping. On the mapping area, components appear as rectangles. The following are
examples of MapForce components:
Constants
Databases
Filters
Conditions
Function components
EDI documents (UN/EDIFACT, ANSI X12, HL7)
Excel 2007+ files
Simple input components
Simple output components
XML Schemas and DTDs
Connector
A connector is a small triangle displayed on the left or right side of a component. The connectors
displayed on the left of a component provide data entry points to that component. The connectors
displayed on the right of a component provide data exit points from that component.
Connection
A connection is a line that you can draw between two connectors. By drawing connections, you
instruct MapForce to transform data in a specific way (for example, read data from an XML
document and write it to another XML document).
Source component
A source component is a component from which MapForce reads data. When you run the
mapping, MapForce reads the data supplied by the connector of the source component, converts
it to the required type, and sends it to the connector of the target component.
Target component
A target component is a component to which MapForce writes data. When you run the mapping,
a target component instructs MapForce to either generate a file (or multiple files) or output the
result as a string value for further processing in an external program. A target component is the
opposite of a source component.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Introduction
2.3
User Interface Overview
21
User Interface Overview
The graphical user interface of MapForce is organized as an integrated development environment.
The main interface components are illustrated below. You can change the interface settings by
using the menu command Tools | Customize.
Use the
buttons displayed in the upper-right corner of each window to show, hide, pin, or
dock it. If you need to restore toolbars and windows to their default state, use the menu
command Tools | Restore Toolbars and Windows.
MapForce graphical user interface (MapForce Professional Edition)
Menu Bar and Toolbars
The Menu Bar displays the menu items. Each toolbar displays a group of buttons
representing MapForce commands. You can reposition the toolbars by dragging their
handles to the desired locations.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
22
Introduction
User Interface Overview
Libraries window
The Libraries window lists the MapForce built-in functions, organized by library. The list of
available functions changes based on the transformation language you select. If you have
created user-defined functions, or if you imported external libraries, they also appear in
the Libraries window.
To search functions by name or by description, enter the search value in the text box at
the bottom of the Libraries window. To find all occurrences of a function (within the
currently active mapping), right-click the function, and select Find All Calls from the
context menu. You can also view the function data type and description directly from the
Libraries window. For more information, see Working with Functions.
Project window
MapForce supports the Multiple Document Interface, and allows you to group your
mappings into mapping projects. The Project window shows all files and folders that have
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Introduction
User Interface Overview
23
been added to the project. Project files have the extension *.mfp (MapForce Project). To
search for mappings inside projects, click anywhere inside the Projects window, and
press CTRL + F. For more information, see Working with Mapping Projects.
Mapping pane
The Mapping pane is the working area where you design mappings. You can add
mapping components (such as files, schemas, constants, variables, and so on) to the
mapping area from the Insert menu (see Adding Components to the Mapping). You can
also drag into the Mapping pane functions displayed in the Libraries window (see Working
with Functions).
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
24
Introduction
User Interface Overview
XSLT (XSLT2) pane
The XSLT (or XSLT2) pane displays the XSLT 1.0 (or 2.0) transformation code generated
from your mapping. To switch to this pane, select XSLT (or XSLT 2) as transformation
language, and then click the XSLT tab (or XSLT2 tab, respectively).
This pane provides line numbering and code folding functionality. To expand or collapse
portions of code, click the "+" and "-" icons at the left side of the window. Any portions of
collapsed code are displayed with an ellipsis symbol. To preview the collapsed code
without expanding it, move the mouse cursor over the ellipsis. This opens a tooltip that
displays the code being previewed, as shown in the image below. Note that, if the
previewed text is too big to fit in the tooltip, an additional ellipsis appears at the end of the
tooltip.
To configure the display settings (including indentation, end of line markers, and others),
right-click the pane, and select Text View Settings from the context menu. Alternatively,
click the Text View Settings (
) toolbar button.
XQuery pane
The XQuery pane displays the XQuery transformation code generated from your mapping,
when you click the XQuery button. This pane is available when you select XQuery as
transformation language. This pane also provides line numbering and code folding
functionality, which works in a similar way as in the XSLT pane (see above).
DB Query pane
The DB Query pane allows you to directly query any major database. You can work with
multiple active connections to different databases.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Introduction
User Interface Overview
25
For more information, see Browsing and Querying Databases.
Output pane
The Output pane displays the result of the mapping transformation (for example, an XML
file), when you click the Output button. If the mapping generates multiple files, you can
navigate sequentially through each generated file.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
26
Introduction
User Interface Overview
This pane also provides line numbering and code folding functionality, which works in a
similar way as in the XSLT pane (see above).
StyleVision Output buttons
If you have installed Altova StyleVision (http://www.altova.com/stylevision.html), the
StyleVision output buttons enable you to preview and save the mapping output in HTML,
RTF, PDF, and Word 2007+ formats. This is possible by means of StyleVision Power
Stylesheet (SPS) files designed in StyleVision and assigned to a mapping component in
MapForce.
Overview window
The Overview window gives a bird's-eye view of the Mapping pane. Use it to navigate
quickly to a particular location on the mapping area when the size of the mapping is very
large. To navigate to a particular location on the mapping, click and drag the red
rectangle.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Introduction
User Interface Overview
27
Messages window
The Messages window shows messages, errors, and warnings when you execute a
mapping (see Previewing the Output ) or perform a mapping validation (see Validating
Mappings ).
To highlight on the mapping area the component or structure which triggered the
information, warning, or error message, click the underlined text in the Messages
window.
The results of a mapping execution or validation operation is displayed in the Messages
window with one of the following status icons:
Icon
Description
Operation completed successfully.
Operation completed with warnings.
Operation has failed.
The Message window may additionally display any of the following message types:
information messages, warnings, and errors.
Icon
Description
Denotes an information message. Information messages do not stop the
mapping execution.
Denotes a warning message. Warnings do not stop the mapping
execution. They may be generated, for example, when you do not create
connections to some mandatory input connectors. In such cases, output
will still be generated for those component where valid connections
exist.
Denotes an error. When an error occurs, the mapping execution fails,
and no output is generated. The preview of the XSLT or XQuery code is
also not possible.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
28
Introduction
User Interface Overview
Other buttons in the Messages window enable you to take the following actions:
Icon
Description
Filter messages by severity (information messages, errors, warnings).
Select Check All to include all severity levels (this is the default
behaviour).
Select Uncheck All to remove all severity levels from the filter. In this
case, only the general execution or validation status message is
displayed.
Move selection to the next line.
Move selection to the previous line.
Copy the selected line to clipboard.
Copy the selected line to clipboard, including any lines nested under it.
Copy the full contents of the Messages window to clipboard.
Find a specific text in the Messages window. Optionally, to find only
words, select Match whole word only. To find text while preserving the
upper or lower case, select Match case.
Find a specific text starting from the currently selected line up to the
end.
Find a specific text starting from the currently selected line up to the
beginning.
Clear the Messages window.
When you work with multiple mapping files simultaneously, you might want to display
information, warning, or error messages in individual tabs for each mapping. In this case,
click the numbered tabs available on the left side of the Messages window before
executing or validating the mapping.
Application status bar
The application status bar appears at the bottom of the application window, and shows
application-level information. The most useful of this information are the tooltips that are
displayed here when you move the mouse over a toolbar button. If you are using the 64-bit
version of MapForce, the application name appears in the status bar with the suffix (x64).
There is no suffix for the 32-bit version.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Introduction
2.4
Conventions
29
Conventions
Example files
Most of the data mapping design files (files with .mfd extension, as well as other accompanying
instance files) illustrated or referenced in this documentation are available in the following folders:
(My) Documents\Altova\MapForce2017\MapForce Examples
(My) Documents\Altova\MapForce2017\MapForce Examples\Tutorials
The location of (My) Documents folder depends on your version of Windows.
Windows
Windows
Windows
Windows
Windows
Windows
10
8
7
Vista
Server 2008
Server 2012
Windows XP
Windows Server 2003
C:\Users\<username>\Documents
C:\Documents and Settings\<username>\My
Documents
The example mappings and instance files accompanying MapForce illustrate most aspects of
how it works, and you are highly encouraged to experiment with them as you learn about
MapForce. When in doubt about the possible effects of making changes to the MapForce original
examples, create back-ups before changing them.
Graphical user interface
Some of the images (screen shots) accompanying this documentation depict graphical user
interface elements that may not be applicable to your MapForce edition. In relevant contexts,
images typically include the name of the source mapping design (*.mfd) file, as well as the edition
of MapForce in which the graphic was produced.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
Chapter 3
Tutorials
32
Tutorials
3
Tutorials
The MapForce tutorials are intended to help you understand and use the basic data
transformation capabilities of MapForce in a short amount of time. You can regard these tutorials
as a "crash course" of MapForce. While the goal is not to illustrate completely all MapForce
features, you will be guided through the MapForce basics step-by-step, so it is recommended that
you follow the tutorials sequentially. It is important that you understand each concept before
moving on to the next one, as the tutorials gradually grow in complexity. Basic knowledge of XML
and XML schema will be advantageous.
Convert XML to New Schema
This tutorial shows you how to convert data from an XML structure to another using the
XSLT 2.0 language, without writing any code. You will also learn about MapForce
sequences and items, creating mapping connections, using a function, validating and
previewing a mapping, as well as saving the resulting output to the disk.
Map Multiple Sources to One Target
This tutorial shows you how to read data from two XML files with different schema and
merge it into a single target XML file. You will also learn how to change the name and
instance files of each mapping component, and the concept of "duplicate inputs".
Work with Multiple Target Schemas
This tutorial shows you how to work with more complex mappings that produce two or
more target outputs. More specifically, you will learn how to generate, in the same
mapping, an XML file that stores a list of book records, and another XML file that contains
only a subset of the books in the first file, filtered by a specific publication year. To
support filtering data, you will use a Filter component, a function and a numeric constant.
Process and Generate Files Dynamically
This tutorial shows you how to read data from multiple XML instance files located in the
same folder and write it to multiple XML files generated on the fly. You will also learn
about stripping the XML and schema declarations and using functions to concatenate
strings and extract file extensions.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Tutorials
3.1
Convert XML to New Schema
33
Convert XML to New Schema
This tutorial shows you how to convert data between two XML files, while helping you learn the
basics of the MapForce development environment. Both XML files store a list of books, but their
elements are named and organized in a slightly different way (that is, the two files have different
schemas).
Ab stract model of the data transformation
The code listing below shows sample data from the file that will be used as data source (for the
sake of simplicity, the XML and the namespace declarations are omitted).
<books>
<book id="1">
<author>Mark Twain</author>
<title>The Adventures of Tom Sawyer</title>
<category>Fiction</category>
<year>1876</year>
</book>
<book id="2">
<author>Franz Kafka</author>
<title>The Metamorphosis</title>
<category>Fiction</category>
<year>1912</year>
</book>
</books>
b ooks.xml
This is how data should look in the target (destination) file:
<library>
<last_updated>2015-06-02T16:26:55+02:00</last_updated>
<publication>
<id>1</id>
<author>Mark Twain</author>
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
34
Tutorials
Convert XML to New Schema
<title>The Adventures of Tom Sawyer</title>
<genre>Fiction</genre>
<publish_year>1876</publish_year>
</publication>
<publication>
<id>2</id>
<author>Franz Kafka</author>
<title>The Metamorphosis</title>
<genre>Fiction</genre>
<publish_year>1912</publish_year>
</publication>
</library>
lib rary.xml
As you may have noticed, some element names in the source and target XML are not the same.
Our goal is to populate the <author>, <title>, <genre> and <publish_year> elements of the
target file from the equivalent elements in the source file (<author>, <title>, <category>,
<year>). The attribute id in the source XML file must be mapped to the <id> element in the target
XML file. Finally, we must populate the <last_updated> element of the target XML file with the
date and time when the file was last updated.
To achieve the required data transformation, let's take the following steps.
Step 1: Select XSLT2 as transformation language
You can do this in one of the following ways:
Click the XSLT2 (
) toolbar button.
On the Output menu, click XSLT 2.0.
Step 2: Add the source XML file to the mapping
The source XML file for this mapping is located at the following path: <Documents>\Altova
\MapForce2017\MapForceExamples\Tutorial\books.xml. You can add it to the mapping in
one of the following ways:
Click the Insert XML Schema/File (
) toolbar button.
On the Insert menu, click XML Schema/File.
Drag the XML file from Windows Explorer into the mapping area.
Now that the file has been added to the mapping area, you can see its structure at a glance. In
MapForce, this structure is known as a mapping component, or simply component. You can
expand elements in the component either by clicking the collapse ( ) and expand icons ( ), or
by pressing the + and - keys on the numeric keypad.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Tutorials
Convert XML to New Schema
35
Mapping component
To move the component inside the mapping pane, click the component header and drag the
mouse to a new position. To resize the component, drag the corner of the component
. You
can also double-click the corner so that MapForce adjusts the size automatically.
The top level node
represents the file name; in this particular case, its title displays the name
of the XML instance file. The XML elements in the structure are represented by the
icon, while
XML attributes are represented by the
icon.
The small triangles displayed on both sides of the component represent data inputs (if they are on
the left side) or outputs (when they are on the right side). In MapForce, they are called input
connectors and output connectors, respectively.
Step 3: Add the target XML schema to the mapping
To generate the target XML, we will use an existing XML schema file. In a real-life scenario, this
file may have been provided to you by a third party, or you can create it yourself with a tool such
as XMLSpy. If you don't have a schema file for your XML data, MapForce prompts you to generate
it whenever you add to the mapping an XML file without an accompanying schema or schema
reference.
For this particular example, we are using an existing schema file available at: <Documents>
\Altova\MapForce2017\MapForceExamples\Tutorial\library.xsd. To add it to the mapping,
follow the same steps as with the source XML file (that is, click the Insert XML Schema/File (
) toolbar button). Click Skip when prompted by MapForce to supply an instance file.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
36
Tutorials
Convert XML to New Schema
At this stage, the mapping design looks as follows:
Step 4: Make the connections
For each <book> in the source XML file, we want to create a new <publication> in the target
XML file. We will therefore create a mapping connection between the <book> element in the
source component and the <publication> element in the target component. To create the
mapping connection, click the output connector (the small triangle) to the right of the <book>
element and drag it to the input connector of the <publication> element in the target.
When you do this, MapForce may automatically connect all elements which are children of
<book> in the source file to elements having the same name in the target file; therefore, four
connections are being created simultaneously. This behavior is called "Auto Connect Matching
Children" and it can be disabled and customized if necessary.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Tutorials
Convert XML to New Schema
37
You can enable or disable the "Auto Connect Matching Children" behavior in one of the following
ways:
Click the Toggle auto connect of children (
) toolbar button.
On the Connection menu, click Auto Connect Matching Children.
Notice that some of the input connectors on the target component have been highlighted by
MapForce in orange, which indicates that these items are mandatory. To ensure the validity of the
target XML file, provide values for the mandatory items as follows:
Connect the <category> element in the source with the <genre> element in the target
Connect the <year> element in the source with the <publish_year> element in the
target
Finally, you need to supply a value to the <last_updated> element. If you move the mouse over
its input connector, you can see that the element is of type xs:dateTime. Note that, for tips to be
displayed, the Show tips (
© 2017 Altova Gmb H
) toolbar button must be enabled.
Altova MapForce 2017 Professional Edition
38
Tutorials
Convert XML to New Schema
You can also make the data type of each item visible at all times, by clicking the Show Data
Types (
) toolbar button.
You can get the current date and time (that is, the xs:dateTime value) by means of a date and
time XSLT function. To find the XSLT function to the mapping, start typing "date" in the text box
located in the lower part of the Libraries window.
As shown above, if you move the mouse over the "result" part of the function, you can see its
description. For tips to be displayed, make sure that the Show tips (
enabled.
) toolbar button is
To add the function to the mapping, drag the function into the mapping pane, and connect its
output to the input of the <last_updated> element.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Tutorials
Convert XML to New Schema
39
You have now created a MapForce mapping design (or simply a "mapping") which converts data
from the books.xml instance file (having the books.xsd schema) to the new library.xml file
(having the library.xsd schema). If you double-click the header of each component, you can view
these and other settings in the Component Settings dialog box, as shown below.
Component settings for the source
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
40
Tutorials
Convert XML to New Schema
Component settings for the target
Step 5: Validate and save the mapping
Validating a mapping is an optional step that enables you to see and correct potential mapping
errors and warnings before you run the mapping. To check whether the mapping is valid, do one of
the following:
On the File menu, click Validate Mapping.
Click the Validate (
) toolbar button.
The Messages window displays the validation results:
Messages window
At this point, you might also want to save the mapping to a file. To save the mapping, do one of
the following:
On the File menu, click Save.
Click the Save (
) toolbar button.
For your convenience, the mapping created in this tutorial is available at the following path:
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Tutorials
Convert XML to New Schema
41
<Documents>\Altova\MapForce2017\MapForceExamples\Tutorial\\BooksToLibrary.mfd.
Therefore, from this point onwards, you can either continue with the mapping file you created, or
with the BooksToLibrary.mfd file.
Step 6: Preview the mapping result
You can preview the result of the mapping directly in MapForce. To do this, click the Output
button located in the lower part of the mapping pane. MapForce runs the transformation and
displays the result of the mapping in the Output pane.
Output pane
You can now see the result of the transformation in MapForce.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
42
Tutorials
Convert XML to New Schema
By default, the files displayed for preview in the Output pane are not written to the disk.
Instead, MapForce creates temporary files. To save the file displayed in the Output pane to
the disk, select the menu command Output | Save Output File, or click the Save
generated output (
) toolbar button.
To configure MapForce to write the output directly to final files instead of temporary, go to
Tools | Options | General, and then select the Write directly to final output files check
box. Note that enabling this option is not recommended while you follow this tutorial, because
you may unintentionally overwrite the original tutorial files.
You can also preview the generated XSLT code that performs the transformation. To preview the
code, click the XSLT2 button located in the lower area of the mapping pane.
XSLT2 pane
To generate and save the XSLT2 code to a file, select the menu item File | Generate Code in |
XSLT 2.0. When prompted, select a folder where the generated code must be saved. After code
generation completes, the destination folder includes the following two files:
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Tutorials
Convert XML to New Schema
1.
2.
43
An XSLT transformation file, named after the target schema (in this example,
MappingMaptolibrary.xslt).
A DoTransform.bat file. The DoTransform.bat file enables you to run the XSLT
transformation in RaptorXML Server (for more information, see http://www.altova.com/
raptorxml.html ).
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
44
3.2
Tutorials
Map Multiple Sources to One Target
Map Multiple Sources to One Target
In the previous tutorial, you have converted data from a source file (books.xml) to a target file
(library.xml). The target file (library.xml) did not exist before running the mapping; it was
generated by the mapping transformation. Let's now imagine a scenario where you already have
some data in the library.xml file, and you want to merge this data with data converted from the
books.xml. The goal in this tutorial is to design a mapping that generates a file called
merged_library.xml. The generated file will include data from two sources: the books.xml file
and the library.xml file. Note that the files used as source (books.xml and library.xml) have
different schemas. If the source files had the same schema, you could also merge their data
using a different approach (see Process and Generate Files Dynamically ).
Ab stract model of the data transformation
To achieve the required goal, let's take the following steps.
Step 1: Prepare the mapping design file
This tutorial uses as starting point the BooksToLibrary.mfd mapping from the <Documents>
\Altova\MapForce2017\MapForceExamples\Tutorial\ folder. You have already designed this
mapping in the Convert XML to New Schema tutorial. To begin, open the BooksToLibrary.mfd
file in MapForce, and save it with a new name.
Make sure to save the new mapping in the <Documents>\Altova\MapForce2017
\MapForceExamples\Tutorial\ folder, because it references several files from it.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Tutorials
Map Multiple Sources to One Target
45
BooksToLib rary.mfd (MapForce Basic Edition)
Step 2: Create a second source component
First, select the target component and copy it (press Ctrl + C), and then paste it (press Ctrl + V)
into the same mapping. Click the header of the new component and drag it under the books
component.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
46
Tutorials
Map Multiple Sources to One Target
The mapping now has two source components: books and library, and one target component:
library.
You can always move the mapping components in any direction (left, right, top, bottom).
Nevertheless, placing a source component to the left of a target component will make your
mapping easier to read and understand by others. This is also the convention for all mappings
illustrated in this documentation, as well as in the sample mapping files accompanying your
MapForce installation.
Step 3: Verify and set the input/output files
In the previous step, the new source component was copy-pasted from the target component, so
it inherits the same settings. To ensure that the name input/output instance files are correctly set,
double-click the header of each component, and, in the Component Settings dialog box, verify and
change the name and the input/output files of each component as shown below.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Tutorials
Map Multiple Sources to One Target
47
Components settings for the first source (books)
Component settings for the second source (library)
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
48
Tutorials
Map Multiple Sources to One Target
Component settings for the target (merged_library)
As shown above, the first source component reads data from books.xml. The second source
component reads data from library.xml. Finally, the target component outputs data to a file
called merged_library.xml.
Step 4: Make the connections
To instruct MapForce to write data from the second source to the target, click the output
connector (small triangle) of the publications item in the source library component and drag it
to the input connector of the publications item in the target library component. Because the
target input connector already has a connection to it, the following notification message appears.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Tutorials
Map Multiple Sources to One Target
49
In this particular tutorial, replacing the connection is not what we want to achieve; our goal is to
map data from two sources. Therefore, click Duplicate Input. By doing so, you configure the
target component to accept data from the new source as well. The mapping now looks as follows:
Notice that the publication item in the target component has now been duplicated. The new
publication(2) node will accept data from the source library component. Importantly, even
though the name of this node appears as publication(2) in the mapping, its name in the
resulting XML file will be publication, which is the intended goal.
You can now click the Output button at the bottom of the mapping pane, and view the mapping
result. You will notice that data from both library.xml and books.xml files has now been merged
into the new merged_library.xml file.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
50
3.3
Tutorials
Work with Multiple Target Schemas
Work with Multiple Target Schemas
In the previous tutorial, Map Multiple Sources to One Target, you have seen how to map data from
multiple source schemas to a single target schema. You have also created a file called
merged_library.xml, which stores book records from two sources. Now let's assume that
someone from another department has asked you to provide a subset of this XML file.
Specifically, you must deliver an XML file that includes only the books published after 1900.
For convenience, you can modify the existing MultipleSourcesToOneTarget.mfd mapping so
that, whenever required, you can generate both the complete XML library, and the filtered library.
Ab stract model of the data transformation
In the diagram above, the data is first merged from two different schemas (books.xsd and
library.xsd) into a single XML file called merged_library.xml. Secondly, the data is transformed
using a filtering function and passed further to the next component, which creates an XML file
called filtered_library.xml. The "intermediate" component acts both as data target and source.
In MapForce, this technique is known as "chaining mappings", which is also the subject of this
tutorial.
Our goal is to make it possible to generate at any time both the merged_library.xml and the
filtered_library.xml. To achieve the goal, let's take the following steps.
Step 1: Prepare the mapping design file
This tutorial uses as starting point the MultipleSourcesToOneTarget.mfd mapping from the
<Documents>\Altova\MapForce2017\MapForceExamples\Tutorial\ folder. You have already
designed this mapping in the Map Multiple Sources to One Target tutorial. To begin, open the
MultipleSourcesToOneTarget.mfd file in MapForce, and save it with a new name.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Tutorials
Work with Multiple Target Schemas
51
Make sure to save the new mapping in the <Documents>\Altova\MapForce2017
\MapForceExamples\Tutorial\ folder, because it references several files from it.
MultipleSourcesToOneTarget.mfd (MapForce Basic Edition)
Step 2: Add and configure the second target component
To add the second target component, click the Insert XML Schema/File (
) toolbar button,
and open the library.xsd file located in the <Documents>\Altova\MapForce2017
\MapForceExamples\Tutorial\ folder. Click Skip when prompted to supply a sample instance
file. The mapping now looks as follows:
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
52
Tutorials
Work with Multiple Target Schemas
As shown above, the mapping now has two source components: books and library, and two
target components. To distinguish between the target components, we will rename the second
one to filtered_library, and also set the name of the XML file that should be generated by it. To
do this, double-click the header of the right-most component and edit the component settings as
follows:
Notice that the new name of the component is filtered_library, and the output XML file is named
filtered_library.xml.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Tutorials
Work with Multiple Target Schemas
53
Step 3: Make the connections
Create a connection from the item publication in the merged_library to the item publication in
the filtered_library. When you do this, a notification message is displayed.
Click OK. Notice that new buttons are now available in the upper-right corner of both target
components: Preview (
) and Pass-through (
). These buttons will be used and
explained in the following steps.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
54
Tutorials
Work with Multiple Target Schemas
Step 4: Filter data
To filter data before supplying it to the filtered_library, we will use a Filter component. To add a
filter component, right-click the connection between merged_library and filtered_library, and
select Insert Filter: Nodes/Rows from the context menu.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Tutorials
Work with Multiple Target Schemas
55
The filter component has now been added to the mapping.
As shown above, the bool input connector is highlighted in orange, which suggests that an input
is required. If you move the mouse over the connector, you can see that an input of type
xs:boolean is required. Note that, for tips to be displayed, the Show tips (
) toolbar button
must be enabled.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
56
Tutorials
Work with Multiple Target Schemas
The filter component requires a condition that returns either true or false. When the Boolean
condition returns true, data of the current publication sequence will be copied over to the target.
When the condition returns false, data will not be copied.
In this tutorial, the required condition is to filter all books which were published after 1900. To
create the condition, do the following:
1.
Add a constant of numeric type having the value "1900" (On the Insert menu, click
Constant). Choose Number as type.
2.
3.
In the Libraries window, locate the function greater and drag it to the mapping pane.
Make the mapping connections to and from the function greater as shown below. By
doing this, you are instructing MapForce: "When publish_year is greater than 1900,
copy the current publication source item to the publication target item".
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Tutorials
Work with Multiple Target Schemas
57
Step 5: Preview and save the output of each target component
You are now ready to preview and save the output of both target components. When multiple
target components exist in the same mapping, you can choose which one to preview by clicking
the Preview (
) button. When the Preview button is in a pressed state (
), it indicates
that that specific component is currently enabled for preview (and this particular component will
generate the output in the Preview pane). Only one component at a time can have the preview
enabled.
Therefore, when you want to view and save the output of the merged_library (that is, the
"intermediate") component, do the following:
1.
2.
3.
Click the Preview button (
) on the merged_library component.
Click the Output button at the bottom of the mapping pane.
On the Output menu, click Save Output File if you want to save the output to a file.
When you want to view and save the output of the filtered_library component :
1.
2.
3.
4.
Click the Pass-through button (
) on the merged_library component.
Click the Preview button (
) on the filtered_library component.
Click the Output button at the bottom of the mapping pane.
On the Output menu, click Save Output File if you want to save the output to a file.
Notice the Pass-through (
) button—clicking or not clicking it makes a big difference in any
mapping which has multiple target components, including this one. When this button is in a
pressed state (
), MapForce lets data pass through the intermediate component, so that you
can preview the result of the entire mapping.
Release the button (
) if you want to preview only the portion of the mapping between the
merged_library and the filtered_library. In the latter case, an error will be generated. This
behavior is expected, because the intermediate component does not have a valid input XML file
from which it should read data. To solve the problem, double-click the header of the component
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
58
Tutorials
Work with Multiple Target Schemas
and edit so as to supply a valid input XML file, as shown below:
You have now finished designing a mapping which has multiple target components, and you can
view and save the output of each target, which was the intended goal of this tutorial. For further
information about working with pass-through components, see Chained mappings / pass-through
components.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Tutorials
3.4
Process and Generate Files Dynamically
59
Process and Generate Files Dynamically
This tutorial shows you how to read data from multiple source XML files and write it to multiple
target files in the same transformation. To illustrate this technique, we will now create a mapping
with the following goals:
1.
2.
3.
4.
Read data from multiple XML files in the same directory.
Convert each file to a new XML schema.
For each source XML file, generate a new XML target file under the new schema.
Strip the XML and namespace declaration from the generated files.
Ab stract model of the data transformation
We will use three source XML files as example. The files are located in the <Documents>\Altova
\MapForce2017\MapForceExamples\Tutorial\ folder, and they are named bookentry1.xml,
bookentry2.xml, and bookentry3.xml. Each of the three files stores a single book.
<?xml version="1.0" encoding="UTF-8"?>
<books xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="books.xsd">
<book id="1">
<author>Mark Twain</author>
<title>The Adventures of Tom Sawyer</title>
<category>Fiction</category>
<year>1876</year>
</book>
</books>
b ookentry1.xml
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
60
Tutorials
Process and Generate Files Dynamically
<?xml version="1.0" encoding="UTF-8"?>
<books xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="books.xsd">
<book id="2">
<author>Franz Kafka</author>
<title>The Metamorphosis</title>
<category>Fiction</category>
<year>1912</year>
</book>
</books>
b ookentry2.xml
<?xml version="1.0" encoding="UTF-8"?>
<books xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="books.xsd">
<book id="3">
<author>Herman Melville</author>
<title>Moby Dick</title>
<category>Fiction</category>
<year>1851</year>
</book>
</books>
b ookentry3.xml
The source XML files use the books.xsd schema available in the following folder: <Documents>
\Altova\MapForce2017\MapForceExamples\Tutorial\. To convert the source files to a new
XML schema, we will use the library.xsd schema (available in the same folder). After the
transformation, the mapping will generate three files according to this new schema (see the code
listings below). We will also configure the mapping so that the name of the generated files will be:
publication1.xml, publication2.xml, and publication3.xml. Notice that the XML declaration
and the namespace declaration must be stripped.
<library>
<publication>
<id>1</id>
<author>Mark Twain</author>
<title>The Adventures of Tom Sawyer</title>
<genre>Fiction</genre>
<publish_year>1876</publish_year>
</publication>
</library>
pub lication1.xml
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Tutorials
Process and Generate Files Dynamically
61
<library>
<publication>
<id>2</id>
<author>Franz Kafka</author>
<title>The Metamorphosis</title>
<genre>Fiction</genre>
<publish_year>1912</publish_year>
</publication>
</library>
pub lication2.xml
<library>
<publication>
<id>3</id>
<author>Herman Melville</author>
<title>Moby Dick</title>
<genre>Fiction</genre>
<publish_year>1851</publish_year>
</publication>
</library>
pub lication3.xml
To achieve the goals, let's take the following steps.
Step 1: Prepare the mapping design file
This tutorial uses as starting point the BooksToLibrary.mfd mapping from the <Documents>
\Altova\MapForce2017\MapForceExamples\Tutorial\ folder. You have already designed this
mapping in the Convert XML to New Schema tutorial. To begin, open the BooksToLibrary.mfd
file in MapForce, and save it with a new name, in the same folder.
Make sure to save the new mapping in the <Documents>\Altova\MapForce2017
\MapForceExamples\Tutorial\ folder, because it references several files from it.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
62
Tutorials
Process and Generate Files Dynamically
BooksToLib rary.mfd (MapForce Basic Edition)
Step 2: Configure the input
To instruct MapForce to process multiple XML instance files, double-click the header of the
source component. In the Component Settings dialog box, enter bookentry*.xml as input file.
Component Settings dialog b ox
The asterisk ( * ) wildcard character in the file name instructs MapForce to use as mapping input
all the files that have the bookentry- prefix. Because the path is a relative one, MapForce will
look for all bookentry- files in the same directory as the mapping file. Note that you could also
enter an absolute path if necessary, while still using the * wildcard character.
Step 3: Configure the output
To create the file name of each output file, we will use the concat function. This function
concatenates (joins) all the values supplied to it as argument.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Tutorials
Process and Generate Files Dynamically
63
To build the file name using the concat function:
1.
Search for the concat function in the Libraries window and drag it to the mapping area.
By default, this function is added to the mapping with two parameters; however, you can
add new parameters if necessary. Click the Add parameter ( ) symbol inside the
function component and add a third parameter to it. Note that clicking the Delete
parameter ( ) symbol deletes a parameter.
2.
Insert a constant (on the Insert menu, click Constant). When prompted to supply a
value, enter "publication" and leave the String option unchanged.
3.
Connect the constant with value1 of the concat function.
4.
Connect the id attribute of the source component with value2 of the concat function.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
64
Tutorials
5.
Process and Generate Files Dynamically
Search for the get-fileext function in the Libraries window and drag it to the mapping
area. Create a connection from the top node of the source component (File: books.xml)
to the filepath parameter of this function. Then create a connection from the result of the
get-fileext function to value3 of the concat function. By doing this, you are extracting
only the extension part (in this case, .xml) from the source file name.
So far, you have provided as parameters to the concat function the three values which, when
joined together, will create the generated file name (for example, publication1.xml):
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Tutorials
Process and Generate Files Dynamically
Part
Example
The constant "publication" supplies the constant string value
"publication".
publication
The attribute id of the source XML file supplies a unique
identifier value for each file. This is to prevent all files from
being generated with the same name.
1
The get-fileext function returns the extension of the file
name to be generated.
.xml
65
You can now instruct MapForce to actually build the file name when the mapping runs. To do this,
click the File (
) or File/String (
) button of the target component and select Use
Dynamic File Names Supplied by Mapping.
You have now instructed MapForce to generate the instance files dynamically, with whatever
name will be provided by the mapping. In this particular example, the name is created by the
concat function; therefore, we will connect the result of the concat function with the File:
<dynamic> node of the target component.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
66
Tutorials
Process and Generate Files Dynamically
If you double-click the target component header at this time, you will notice that the Input XML
File and Output XML File text boxes are disabled, and their value shows <File names
supplied by the mapping>.
This serves as an indication that you have supplied the instance file names dynamically from a
mapping, so it is no longer relevant to define them in the component settings.
Finally, you need to strip the XML namespace and schema declaration from the target. To achieve
this, clear the selection from the Add schema/DTD reference... and Write XML Declaration
check boxes on the Component Settings dialog box.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Tutorials
Process and Generate Files Dynamically
67
You can now run the mapping and see the result, as well as the name of generated files. This
mapping generates multiple output files. You can navigate through the output files using the left
and right buttons in the upper left corner of the output pane, or by picking a file from the adjacent
drop-down list.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
Chapter 4
Common Tasks
70
Common Tasks
4
Common Tasks
This section describes common MapForce tasks and concepts, such as working with mappings,
components, connections, and mapping projects.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
4.1
Working with Mappings
71
Working with Mappings
A MapForce mapping design (or simply "mapping") is the visual representation of how data is to
be transformed from one format to another. A mapping consists of components that you add to
the MapForce mapping area in order to create your data transformations (for example, convert
XML documents from one schema to another). A valid mapping consists of one or several source
components connected to one or several target components. You can run a mapping and preview
its result directly in MapForce. You can generate code and execute it externally. You can also
compile a mapping to a MapForce execution file and automate mapping execution using
MapForce Server or FlowForce Server. MapForce saves mappings as files with .mfd extension.
To create a new mapping:
1.
2.
Do one of the following:
o On the File menu, click New.
o Click the New (
) toolbar button.
Click Mapping, and then click OK.
Your mapping is now created; however, it does not yet do anything because it is empty. A
mapping requires at least two connected components to become valid, so the next step is to add
components to the mapping (see Adding Components to the Mapping ) and draw connections
between components (see Working with Connections ).
4.1.1
Adding Components to the Mapping
In MapForce, the term "component" is what represents visually the structure (schema) of your
data, or how data is to be transformed (functions). Components are the central building pieces of
any mapping. On the mapping area, components appear as rectangles. The following are
examples of MapForce components:
Constants
Databases
Filters
Conditions
Function components
EDI documents (UN/EDIFACT, ANSI X12, HL7)
Excel 2007+ files
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
72
Common Tasks
Working with Mappings
Simple input components
Simple output components
XML Schemas and DTDs
To add a component to the mapping, do one of the following:
On the Insert menu, click the option relevant for the component type you wish to add (for
example, XML Schema/File).
Drag a file from Windows File Explorer onto the mapping area. Note that this operation is
possible only for compatible file-based components.
Click the relevant button on the Insert Component toolbar.
Insert Component toolb ar (MapForce Enterprise Edition)
Each component type has specific purpose and behavior. For component types where that is
necessary, MapForce walks you through the process by displaying contextual wizard steps or
dialog boxes. For example, if you are adding an XML schema, a notification dialog box prompts
you to optionally select an instance file as well.
For an introduction to components, see Working with Components. For specific information about
each technology supported as mapping source or target, see Data Sources and Targets. For
information about MapForce built-in components used to store data temporarily or transform it
(such as filtering or sorting), see Designing Mappings.
4.1.2
Adding Components from a URL
In addition to adding local files as mapping components, you can also add files from a URL. Note
that this operation is supported when you add a component as source component (that is, your
mapping reads data from the remote file).
To add a component from a URL:
1.
2.
On the Insert menu, select the type of the component type you wish to add (for
example, XML Schema/File).
On the Open dialog box, click Switch to URL.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
3.
Working with Mappings
73
Enter the URL of the file in the File URL text box, and click Open.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
74
Common Tasks
Working with Mappings
Make sure that the file type in the File URL text box is the same as the file type you
specified in step 1.
If the server requires password authentication, you will be prompted to enter the user name and
password. If you want the user name and password to be remembered next time you start
MapForce, enter them in the Open dialog box and select the Remember password between
application starts check box.
The Open As setting defines the grammar for the parser when opening the file. The default and
recommended option is Auto.
If the file you are loading is not likely to change, select the Use cache/proxy option to cache
data and speed up loading the file. Otherwise, if you want the file to be reloaded each time when
you open the mapping, select Reload.
For servers with Web Distributed Authoring and Versioning (WebDAV) support, you can browse
files after entering the server URL in the Server URL text box and clicking Browse. Although the
preview shows all file types, make sure that you choose to open the same file type as specified in
step 1 above; otherwise, errors will occur.
If the server is a Microsoft SharePoint Server, select the This is a Microsoft SharePoint Server
check box. Doing so displays the check-in or check-out state of the file in the preview area. If you
want to make sure that no one else can edit the file on the server while you are using it in
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
Working with Mappings
75
MapForce to read data from it, right-click the file and select Check Out. To check in any file that
was previously checked out by you, right-click the file and select Check In.
Open dialog box (in Switch to URL mode)
4.1.3
About Data Streaming
Data streaming is a MapForce built-in mechanism that allows you to use arbitrarily large data
sources as input or output to your mappings. Data streaming should not be confused with stream
objects in MapForce generated code. (The latter represent a possible way of handling data if you
integrate MapForce generated code with a custom C# and Java application.)
Data streaming applies to the following data sources:
XML files
CSV files
Fixed-length field files
Databases
When you use any of the above data sources as input or output in your mappings, MapForce
treats the data source as an open stream of data, and processes its contents sequentially,
instead of loading all data into the memory.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
76
Common Tasks
Note:
Working with Mappings
Data streaming is possible only if you have selected BUILT-IN as transformation language
(see Selecting a transformation language ).
Memory usage considerations
When you work with mapping inputs and outputs that are data streaming candidates, “Out of
memory” errors can occur if your mapping requires random access to the input source.
For example, let’s assume that your mapping contains a component that applies a group-by
function on the source data. If you apply the group-by function on the entire tree structure of the
input file, this would require the entire source file to be loaded into memory, and, consequently,
file streaming would no longer be possible. The same is true for any operation which would require
the whole contents of the mapping source to be loaded into memory, such as sorting.
When situations such as the one described above occur, the transformation will nevertheless
complete successfully if there is enough virtual memory and disk space available on your
system.
4.1.4
Selecting a Transformation Language
To meet your data mapping needs, MapForce provides the ability to choose between various
transformation languages.
By default, MapForce provides a robust, built-in engine capable of performing the same
transformations supported in other languages. When you deploy MapForce mappings to
MapForce Server, the built-in engine executes them without the need for any external processors.
Furthermore, if you require minimal or no manual intervention in your data transformation process,
you can use FlowForce Server to automate mapping processes by means of scheduled jobs.
Consider choosing the transformation language after testing several approaches and determining
what works best for your data. The available transformation languages are as follows:
BUILT-IN (This is the default native transformation engine used by MapForce.)
C++
C#
Java
XQuery
XSLT 1.0
XSLT 2.0
To select a transformation language, do one of the following:
On the Output menu, click the name of the language you wish to use for transformation.
Click the name of the language in the Language Selection toolbar.
Note:
Some mapping inputs and outputs are not supported by certain languages. For example,
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
Working with Mappings
77
if you use a database as mapping input or output, you cannot generate XSLT code.
Therefore, if you attempt to generate the code or preview the output of a mapping that has
sources or targets not supported by the selected language, MapForce displays a relevant
notification message.
Using the BUILT-IN option
When you select BUILT-IN (
) as a transformation language for your mapping, MapForce uses
its internal transformation engine to execute the data mapping. MapForce also uses this option
implicitly, whenever you want to preview the output of a mapping where the selected
transformation language is Java, C#, or C++.
It is recommended to set the transformation language to BUILT-IN in the following cases:
As default option, when you do not necessarily need to use a specific language to
transform data.
If you are processing large files and memory usage is a concern.
4.1.5
Validating Mappings
MapForce validates mappings automatically, when you click the Output tab to preview the
transformation result. You can also validate a mapping explicitly, before attempting to preview its
result. This helps you identify and correct potential mapping errors and warnings before the
mapping is run. Note that running a mapping may generate additional runtime errors or warnings
depending on the processed data, for example, when values mapped to attributes are overwritten.
To validate a mapping explicitly, do one of the following:
On the File menu, click Validate Mapping.
Click the Validate (
) toolbar button.
The Messages window displays the validation results, for example:
Messages window
When you validate a mapping, MapForce checks for the validity of the mapping (such as incorrect
or missing connections, unsupported component kinds), and the validation result is then
displayed in the Messages window with one of the following status icons:
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
78
Common Tasks
Icon
Working with Mappings
Meaning
Validation has completed successfully.
Validation has completed with warnings.
Validation has failed.
The Message window may additionally display any of the following message types: information
messages, warnings, and errors.
Icon
Meaning
Denotes an information message. Information messages do not stop the
mapping execution.
Denotes a warning message. Warnings do not stop the mapping execution.
They may be generated, for example, when you do not create connections to
some mandatory input connectors. In such cases, output will still be generated
for those component where valid connections exist.
Denotes an error. When an error occurs, the mapping execution fails, and no
output is generated. The preview of the XSLT or XQuery code is also not
possible.
To highlight on the mapping area the component or structure which triggered the information,
warning, or error message, click the underlined text in the Messages window.
For components that transform data (such as functions or variables), MapForce validation works
as follows:
If a mandatory input connector is unconnected, an error message is generated and the
transformation is stopped.
If an output connector is unconnected, then a warning is generated and the
transformation process continues. The offending component and its data are ignored and
are not mapped to the target document.
To display the result of each validation in an individual tab, click the numbered tabs available on
the left side of the Messages window. This may be useful, for example, if you work with multiple
mapping files simultaneously
Other buttons in the Messages window enable you to take the following actions:
Filter the message by types (for example, to show only errors or warnings)
Move up or down through the entries
Copy the message text to the clipboard
Find a specific text in the window
Clear the Messages window.
For general information about the Messages window, see User Interface Overview.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
4.1.6
Working with Mappings
79
Validating the Mapping Output
After you click the Output tab to preview the mapping, the resulting output becomes available in
the Output pane. You can validate this output against the schema associated with it. For
example, if the mapping transformation generates an XML file, then the resulting XML document
can be validated against the XML schema.
For XML files, you can specify the schema associated with the instance file in the Add Schema/
DTD reference field of the Component Settings dialog box (see XML Component Settings ). The
path specifies where the schema file referenced by the produced XML output is to be located. This
ensures that the output instance can be validated when the mapping is executed. You can enter
an http:// address in this field, as well as an absolute or relative path. If you do not select the
Add Schema/DTD reference field, then the validation of the output file against the schema is not
possible. If you select this check box but leave it empty, then the schema filename of the
Component Settings dialog box is generated into the output and the validation is done against it.
To validate the mapping output, do one of the following:
Click the Validate Output
toolbar button.
On the Output menu, click Validate Output File.
Note:
The Validate Output button and its corresponding menu command (Output | Validate
Output File) are enabled only if the output file supports validation against a schema.
The result of the validation is displayed in the Messages window, for example:
If the validation was not successful, the message contains detailed information on the errors that
occurred.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
80
Common Tasks
Working with Mappings
The validation message contains a number of hyperlinks you can click for more detailed
information:
Clicking the file path opens the output of the transformation in the Output tab of
MapForce.
Clicking <ElementName> link highlights the element in the Output tab.
Clicking the
icon opens the definition of the element in XMLSpy (if installed).
Clicking the hyperlinks in the Details subsection (e.g., cvc-model-group) opens a
description of the corresponding validation rule on the http://www.w3.org/ website.
4.1.7
Previewing the Output
When working with MapForce mappings, you can preview the resulting output without having to
run and compile the generated code with an external processor or compiler. In general, it is a
good idea to preview the transformation output within MapForce before attempting to process the
generated code externally.
When you choose to preview the mapping results, MapForce executes the mapping and
populates the Output pane with the resulting output.
Once data is available in the Output pane, you can validate and save it if necessary (see
Validating the Mapping Output ). You can also use the Find command (Ctrl + F key combination)
to quickly locate a particular text pattern within the output file (see also Searching in Text View).
Any errors, warning, or information messages related to the mapping execution are displayed in
the Messages window (see User Interface Overview ).
To preview the transformation output:
Click the Output tab under the Mapping window. MapForce executes the mapping using
the transformation language selected in the Language toolbar and populates the Output
pane with the resulting output.
Note:
If you select C++, C#, or Java as transformation language, MapForce executes the
mapping using its built-in transformation engine. The result that appears in the Output
pane is the same as if the Java, C++, or C# code had been generated, compiled and
executed.
To save the transformation output, do one of the following:
On the Output menu, click Save Output File.
Click the Save Generated Output toolbar button.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
Working with Mappings
81
Partial output preview
When you are previewing large output files, MapForce limits the amount of data displayed in the
Output pane. More specifically, MapForce displays only a part of the file in the Output pane, and
a Load more... button appears in the lower area of the pane. Clicking the Load more... button
appends the next file part to the currently visible data, and so on.
Note:
The Pretty-print button becomes active when the complete file has been loaded into the
Output pane.
You can configure the preview settings from the General tab of the Options dialog box (see
Changing the MapForce Options).
4.1.8
Text View Features
The Output pane, the XSLT pane, as well as the XQuery pane have multiple visual aids to make
the display of text easier. These include:
Line Numbers
Syntax Coloring
Bookmarks
Source Folding
Indentation Guides
End-of-Line and Whitespace Markers
Zooming
Pretty-printing
Word wrapping
Text highlighting
Where applicable, you can toggle or customize the features above from the Text View Settings
dialog box. Settings in the Text View Settings dialog box apply to the entire application—not
only to the active document.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
82
Common Tasks
Working with Mappings
Text View Settings dialog b ox
To open the Text View settings dialog box, do one of the following:
On the Output menu, select Text View Settings.
Click the Text View Settings
toolbar button.
Right-click the Output pane, and select Text View Settings from the context menu.
Some of the navigation aids can also be toggled from the Text View toolbar, the application menu,
or keyboard shortcuts.
Text View toolb ar
For reference to all applicable shortcuts, see the "Key Map" section of the Text View Settings
dialog box illustrated above.
Line numbers
Line numbers are displayed in the line numbers margin, which can be toggled on and off in the
Text View Settings dialog box. When a section of text is collapsed, the line numbers of the
collapsed text are also hidden.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
Working with Mappings
83
Syntax coloring
Syntax coloring is applied according to the semantic value of the text. For example, in XML
documents, depending on whether the XML node is an element, attribute, content, CDATA
section, comment, or processing instruction, the node name (and in some cases the node's
content) is colored differently.
Bookmarks
Lines in the document can be bookmarked for quick reference and access. If the bookmarks
margin is toggled on, bookmarks are displayed in the bookmarks margin.
Otherwise, bookmarked lines are highlighted in cyan.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
84
Common Tasks
Working with Mappings
The bookmarks margin can be toggled on or off in the Text View Settings dialog box.
You can edit and navigate bookmarks using the following commands:
Insert/Remove Bookmark (Ctrl + F2)
Go to Next Bookmark (F2)
Go to Previous Bookmark (Shift + F2)
Delete All Bookmarks (Ctrl + Shift + F2)
The commands above are available in the Output menu. Bookmark commands are also available
through the context menu, when you right-click the Output (or XSLT, or XQuery) pane.
Source folding
Source folding refers to the ability to expand and collapse nodes and is displayed in the source
folding margin. The margin can be toggled on and off in the Text View Settings dialog box. To
expand or collapse portions of text, click the "+" and "-" nodes at the left side of the window. Any
portions of collapsed code are displayed with an ellipsis symbol. To preview the collapsed code
without expanding it, move the mouse cursor over the ellipsis. This opens a tooltip that displays
the code being previewed, as shown in the image below. Note that, if the previewed text is too big
to fit in the tooltip, an additional ellipsis appears at the end of the tooltip.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
The Toggle All Folds
Working with Mappings
85
command toggles all nodes to their expanded or collapsed forms.
Indentation guides
Indentation guides are vertical dotted lines that indicate the extent of a line's indentation. They can
be toggled on and off in the Text View Settings dialog box.
Note: The Insert tabs and Insert spaces options take effect when you use the Output | PrettyPrint XML text option.
End-of-line markers, whitespace markers
End-of-line (EOL) markers and whitespace markers can be toggled on in the Text View Settings
dialog box. The image below shows a document where both end-of-line and whitespace markers
are visible. An arrow represents a tab character, a "CR" is a carriage return, and a dot represents
a space character.
Zooming in and out
You can zoom in and out by scrolling (with the scroll-wheel of the mouse) while holding the Ctrl
key pressed. Alternatively, press the "-" or "+" keys while holding the Ctrl key pressed.
Pretty-printing
The Pretty-Print XML Text command reformats the active XML document in Text View to give a
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
86
Common Tasks
Working with Mappings
structured display of the document. By default, each child node is offset from its parent by four
space characters. This can be customized from the Text View Settings dialog box.
To pretty-print an XML document, select the Output | Pretty-Print XML Text menu command, or
click the Pretty Print
toolbar button.
Word wrapping
To toggle word wrapping in the currently active document, select the Output | Word Wrap menu
command, or click the Word Wrap
toolbar button.
Text highlighting
When you select text, all matches in the document of the text selection that you make are
highlighted automatically. The selection is highlighted in pale blue, and matches are highlighted in
pale orange. The selection and its matches are indicated in the scroll bar by gray marker-squares.
The current cursor position is given by the blue cursor-marker in the scroll bar.
To switch text highlighting on, select Enable auto-highlighting in the Text View Settings dialog
box. A selection can be defined to be an entire word or a fixed number of characters. You can
also specify whether casing should be taken into account or not.
For a character selection, you can specify the minimum number of characters that must match,
starting from the first character in the selection. For example, you can choose to match two or
more characters. In this case, one-character selections will not be matched, but a selection
consisting of two or more characters will be matched. So, in this case, if you select t, then no
matches will be shown; selecting ty will show all ty matches; selecting typ will show all typ
matches; and so on.
For word searches, the following are considered to be separate words: element names (without
angular brackets), the angular brackets of element tags, attribute names, and attribute values
without quotes.
4.1.9
Searching in Text View
The text in the Output pane, the XQuery pane, as well as the XSLT pane can be searched using
an extensive set of options and visual aids.
To start a search , press Ctrl+F (or select the menu command Edit | Find). You can then search
in the entire document or within a text selection for a search term that you enter in the dialog.
Enter a string to find, or use the combo box to select a string from one of the last 10
strings.
When you enter or select a string to find, all matches are highlighted and the positions of
the matches are indicated by beige markers in the scroll bar.
The currently selected match has a different highlight color than the other matches, and
its position is indicated in the scroll bar by the dark blue cursor-marker.
The total number of matches is listed below the search term field, together with the index
position of the currently selected match. For example, 2 of 4 indicates that the second
of four matches is currently selected.
You can move from one match to the next, in both directions, by selecting the Previous
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
Working with Mappings
(Shift+F3) and Next
87
(F3) buttons at bottom right.
To close the Find dialog, click the Close
button at top right, or press Esc.
Note the following points:
The Find dialog is modeless. This means that it can remain open while you continue to
use Text View.
If text is selected prior to opening the dialog box, then the selected text is automatically
inserted into the search term field.
To search within a selection, do the following: (i) Mark the selection; (ii) Toggle on the
Find in Selection
option to lock the selection; (iii) Enter the search term. To search
within another selection, unlock the current selection by toggling off the Find in Selection
option, then make the new selection and toggle on the Find in Selection
option.
After the Find dialog is closed, you can repeat the current search by pressing F3 for a
forward search, or Shift+F3 for a backward search. The Find dialog will appear again in
this case.
Find options
Find criteria can be specified via buttons located below the search term field. When an option is
toggled on, its button color changes to blue. You can select from the following options:
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
88
Common Tasks
Option
Working with Mappings
Icon
Description
Match case
Performs a case-sensitive search when toggled on ("Address" is
not the same as "address").
Match whole word
Only the exact words in the text will be matched. For example, for
the input string fit, with Match whole word toggled on, only the
word fit will match the search string; the fit in fitness, for example,
will not.
Regular
expression
If toggled on, the search term will be read as a regular expression.
See "Using regular expressions" below.
Find anchor
When a search term is entered, the matches in the document are
highlighted and one of these matches will be marked as the current
selection. The Find anchor toggle determines whether that first
current selection is made relative to the cursor position or not. If
Find anchor is toggled on, then the first currently selected match
will be the next match from the current cursor location. If Find
anchor is toggled off, then the first currently selected match will
be the first match in the document, starting from the top.
Find in selection
When toggled on, locks the current text selection and restricts the
search to the selection. Otherwise, the entire document is
searched. Before selecting a new range of text, unlock the current
selection by toggling off the Find in Selection option.
Using regular expressions
You can use regular expressions (regex) to find a text string. To do this, first, switch the Regular
expression
option on. This specifies that the text in the search term field is to be evaluated as
a regular expression. Next, enter the regular expression in the search term field. For help with
building a regular expression, click the Regular Expression Builder
button, which is located
to the right of the search term field. Click an item in the Builder to enter the corresponding regex
metacharacter/s in the search term field. The screenshot below shows a simple regular
expression to find email addresses.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
Working with Mappings
89
The following custom set of regular expression metacharacters are supported when finding and
replacing text.
.
Matches any character. This is a placeholder for a single character.
\(abc\)
The \( and \) metacharacters mark the start and end of a tagged expression.
Tagged expressions may be useful when you need to tag ("remember") a matched
region for the purpose of referring to it later (back-reference). Tagged expressions are
similar to matched subexpressions (indexed groups) in the .NET flavour of regular
expressions. Up to nine sub-expressions can be tagged (and then back-referenced
later).
For example, \(the\) \1 matches the string the the. This expression can be
literally explained as follows: match the string "the" (and remember it as a tagged
region), followed by a space character, followed by a back-reference to the tagged
region matched previously.
\n
Where n is 1 through 9 , n refers to the first through ninth tagged region (see
above).
\<
Matches the start of a word.
\>
Matches the end of a word.
\
Escapes the character following the backslash. In other words, the expression \x
allows you to use the character x literally. For example, \[ would be interpreted as
[ and not as the start of a character set.
[...]
Matches any characters in this set. For example, [abc] matches any of the
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
90
Common Tasks
Working with Mappings
characters a, b or c. You can also use ranges: for example [a-z] for any lower
case character.
[^...]
Matches any characters not in this set. For example, [^A-Za-z] matches any
character except an alphabetic character.
^
Matches the start of a line (unless used inside a set, see above).
$
Matches the end of a line. For example, A+$ matches one or more A's at end of line.
*
Matches zero or more occurrences of the preceding expression. For example, Sa*m
matches Sm, Sam, Saam, Saaam and so on.
+
Matches one or more occurrences of the preceding expression. For example, Sa+m
matches Sam, Saam, Saaam and so on.
Finding special characters
You can search for any the following special characters within text, provided that the Regular
expression option
is enabled:
\t (Tab)
\r (Carriage Return)
\n (New line)
\\ (Backslash)
For example, to find a tab character, press Ctrl + F, select the
the Find dialog box.
4.1.10
option, and then enter \t in
Previewing the XSLT Code
You can preview the XSLT code generated by MapForce if you selected XSLT 1.0 or XSLT 2.0 as
data transformation language (see Selecting a transformation language).
To preview the generated XSLT 1.0 (or XSLT 2.0) code, do one of the following:
To preview the XSLT 1.0 code, click the XSLT tab under the Mapping window.
To preview the XSLT 2.0 code, click the XSLT2 tab under the Mapping window.
Note:
4.1.11
The XSLT (or XSLT2) tab becomes available if you have selected XSLT (or XSLT2,
respectively) as transformation language.
Generating XSLT Code
To generate XSLT code:
1.
2.
Select the menu item File | Generate code in | XSLT 1.0 (XSLT 2.0).
Select the folder you want to save the generated XSLT file, and click OK. MapForce
generates the code and displays the result of the operation in the Messages window.
The name of the generated .xslt file has the form <A>MapTo<B>.xslt, where:
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
Working with Mappings
91
"<A>" is the value of the Application Name field in mapping settings (see Changing the
Mapping Settings).
"<B>" is the name of the target mapping component. To change this value, open the
settings of the target component and edit the value of the Component Name field (see
Changing the Component Settings).
The folder where the .xslt file is saved also contains a batch file called DoTransform.bat which
can be run with RaptorXML Server to transform the data.
To run the transformation with RaptorXML Server:
1.
2.
Download and install RaptorXML from the download page (http://www.altova.com/
download-trial-server.html).
Start the DoTransform.bat batch file located in the previously designated output folder.
Note that you might need to add the RaptorXML installation location to the path variable of the
Environment Variables. You can find the RaptorXML documentation on the website documentation
page (http://www.altova.com/documentation.html).
4.1.12
Previewing the XQuery Code
You can preview the XQuery code generated by MapForce if you selected XQuery as data
transformation language (see Selecting a transformation language ).
To preview the generated XQuery code:
Click the XQuery tab under the Mapping window.
Note:
4.1.13
The XQuery tab becomes available if you have selected XQuery as transformation
language.
Working with Multiple Mapping Windows
MapForce uses a Multiple Document Interface (MDI). Each mapping file you open in MapForce
has a separate window. This enables you to work with multiple mapping windows and arrange or
resize them in various ways inside the main (parent) MapForce window. You can also arrange all
open windows using the standard Windows layouts: Tile horizontally, Tile vertically, Cascade.
When multiple mappings are open in MapForce, you can quickly switch between them using the
tabs displayed in the lower part of the Mapping pane.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
92
Common Tasks
Working with Mappings
Window management options are available both on the Window menu and on the Windows
dialog box. From the Windows dialog box, you can take actions against any or all currently open
mapping windows (including saving, closing, or minimizing them).
Windows dialog b ox
You can open the Windows dialog box using the menu command Window | Windows... To
select multiple windows in the Windows dialog box, click the required entries while holding the
Ctrl key pressed.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
4.1.14
Working with Mappings
93
Changing the Mapping Settings
You can change the document-specific settings of the currently active mapping design file from
the Mapping Settings dialog box. This information is stored in the *.mfd file.
To open the Mapping Settings dialog box:
On the File menu, click Mapping Settings.
Mapping Settings dialog b ox
The available settings are as follows.
Application Name
Defines the XSLT1.0/2.0 file name prefix or the Java, C# or C
++ application name for the generated transformation files.
Base Pack age Name
Defines the base package name for the Java output.
Mak e paths absolute in
generated code
Defines whether the file paths should be relative or absolute
in the generated code, and in MapForce Server Execution
files (mfx). For more information, see About Paths in
Generated Code.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
94
Common Tasks
Ensure Windows path
convention for file path
Working with Mappings
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.
Line ends
This combo box allows you to specify the line endings of the
output files. "Platform default" is the specific default for the
target operating system, e.g. Windows (CR+LF), Mac OS X
(LF), or Linux (LF). You can also select a specific line ending
manually. The settings you select here are crucial when you
deploy a mapping to FlowForce Server running on a different
operating system.
XML Schema Version
Lets you define the XML Schema Version used in the
mapping file. You can define if you always want to load the
Schemas conforming to version 1.0 or 1.1. Note that not all
version 1.1 specific features are currently supported.
If the xs:schema vc:minVersion="1.1" declaration is present,
then version 1.1 will be used; if not, version 1.0 will be used.
If the XSD document has no vc:minVersion attribute or the
value of the vc:minVersion attribute is other than 1.0 or
1.1, then XSD 1.0 will be the default mode.
Note:
Do not confuse the vc:minVersion attribute with
the xsd:version attribute. The former holds the XSD
version number, while the latter holds the document
version number.
Changing this setting in an existing mapping causes a
reloading of all schemas of the selected XML schema
version, and might also change its validity.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
4.2
Working with Components
95
Working with Components
Components are the central elements of any mapping design in MapForce. Generally, the term
"component" is a convenient way to call any object which acts as a data source, or as a data
target, or represents your data in the mapping at an intermediary processing stage.
There are two main categories of components: structure components and transformation
components.
The structure components represent the abstract structure or schema of your data. For example,
when you add an XML file to the mapping area (using the menu command Insert | XML Schema/
File), it becomes a mapping component. For further information about structure components and
their specifics, see Data Sources and Targets. With a few exceptions, structure components
consist of items and sequences. An item is the lowest level mapping unit (for example, a single
attribute in the XML file, or an element of simple type). A sequence is a collection of items.
The transformation components either transform data (for example, functions), or assist you in
transformations (for example, constants or variables). For information on how you can use these
components to achieve various data transformation tasks, see Designing Mappings.
With the help of structure components, you can either read data from files or other sources, write
data to files or other sources, or store data at some intermediary stage in the mapping process
(for example, in order to preview it). Consequently, structure components can be of the following
types:
Source. You declare a component as source by placing it on the left of the mapping area,
and, thus, instructing MapForce to read data from it.
Target. You declare a component as target by placing on the right of the mapping area,
and, thus, instructing MapForce to write data to it.
Pass-through. This is a special component type which acts both as a source and target
(for further information, see Chained mappings / pass-through components).
On the mapping area, components appear as rectangles. The following sample mapping
illustrates three source components, one target XML component, and various transformation
components (functions and filters) through which data goes before being written to the source.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
96
Common Tasks
Working with Components
CompletePO.mfd
This mapping sample is available at the following path: <Documents>\Altova\MapForce2017
\MapForceExamples\CompletePO.mfd.
4.2.1
Searching within Components
To search for a specific node/item in a component:
1.
2.
Click the component you want to search in, and press the CTRL+F keys.
Enter the search term and click Find Next.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
Working with Components
97
Use the Advanced options to define which items (nodes) are to be searched, as well as restrict
the search options based on the specific connections.
4.2.2
Aligning Components
When you move components in the mapping pane, MapForce displays auto-alignment guide
lines. These guide lines help you align a component to any other component in the mapping
window.
In the sample mapping below, the lower component is being moved. The guide lines show that it
can be aligned to the component on the left side of the mapping.
Component auto-alignment guide lines
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
98
Common Tasks
Working with Components
To enable or disable this option:
1.
2.
4.2.3
On the Tools menu, click Options.
In the Editing group, select the Align components on mouse dragging check box.
Changing the Component Settings
After you add a component to the mapping area, you can configure the settings applicable to it
from the Component Settings dialog box. You can open the Component settings dialog box in one
of the following ways:
Select the component and, on the Component menu, click Properties.
Double-click the component header.
Right-click the component header, and then click Properties.
Note that the available options depend on the type of the component. For reference to the settings
applicable to each component type, see:
XML Component Settings
Database Component Settings
CSV Component Settings
Fixed-Length Field Component Settings
For any file-based component, such as XML, a File/String (
) button appears next to
the root node. This button specifies advanced options applicable if you want to process or
generate multiple files in a single mapping (see Processing Multiple Input or Output Files
Dynamically). Additionally, it enables advanced options for parsing strings or serializing data to
strings (see Parsing and Serializing Strings).
4.2.4
Duplicating Input
Sometimes, you may need to configure a component to accept data from more than one source.
For example, you may need to convert data from two different XML schemas into a single
schema. To make the destination schema accept data from both source schemas, you can
duplicate any of the input items in the component. Duplicating input is meaningful only for a
component which is a target component. On any given target component, you can duplicate as
many items as required.
To duplicate a particular input item, right-click it and select Add Duplicate Input After/Before
from the context menu.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
Working with Components
99
In the image above, the item LineItem is being duplicated in order to provide the ability to map
data from a second source.
Once you duplicate an input, you can make connections both to the original input and to the
duplicate input. For example, this would enable you to copy data from source A to original input,
and data from source B to the duplicate input.
Note:
Duplication of XML attributes is not allowed, as it would make the resulting XML instance
invalid. In case of XML elements, duplicating input is allowed regardless of the value of the
element's maxOccurs attribute in the schema. This behaviour is intentional, since the
schema could change later, or the source data could be optional. For example, a
mapping could generate a single XML element, even if the input is duplicated on the
mapping.
For a step-by-step example, see Map Multiple Sources to One Target.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
100
4.3
Common Tasks
Working with Connections
Working with Connections
A mapping is ultimately about transforming data from one format or structure into another. In a
very basic mapping scenario, you add to the mapping area the components which represent your
source and your target data (for example, a source XML schema and a destination one), and then
draw visually the mapping connections between the two structure. A connection is, therefore, the
visual representation of how data is mapped from a source to a destination.
Components have inputs and outputs which appear on the mapping as small triangles, called
connectors. Input connectors are positioned to the left of any item to which you can draw a
connection. Output connectors are positioned to the right of any item from which you can draw a
connection.
To draw a connection between two items:
Click the output connector of a source item and drag it to a destination item. When the
drop action is allowed, a link tooltip appears next to the text cursor.
An input connector accepts only one incoming connection. If you try to add a second connection
to the same input, a message box appears asking if you want to replace the connection with a
new one or duplicate the input item. An output connector can have several connections, each to a
different input.
To move a connection to a different item:
Click the stub of the connection (the straight section closer to the target) and drag it to
the destination.
To copy a connection to a different item:
Click the stub of the connection (the straight section closer to the target), and drag it to
the destination while holding down the Ctrl key.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
Working with Connections
101
To view the item(s) at the other end of a connection:
Point to the straight section of a connection (close to the input/output connector). A
tooltip appears which displays the name(s) of the item(s) at the other end of the
connection. If multiple connections have been defined from the same output, then a
maximum of ten item names are displayed. In the sample below, the two target items
are SinglePrice and value2 of the multiply function.
To change the connection settings, do one of the following:
On the Connection menu, click Properties (this menu item becomes enabled when you
select a connection).
Double-click the connection.
Right-click the connection, and then click Properties.
See also Connection Settings.
To delete a connection, do one of the following:
Click the connection, and then press the Delete key.
Right-click the connection, and then click Delete.
4.3.1
About Mandatory Inputs
To aid you in the mapping process, MapForce highlights in orange the mandatory inputs in target
components:
In XML and EDI components these are items where the minOccurs parameter is equal/
greater than 1.
In databases these are fields that have been defined as "not null"
WSDL calls and WSDL response (all nodes)
XBRL nodes that have been defined as mandatory
In functions these are the specific mandatory parameters such that once one parameter
has been mapped, then the other mandatory ones will be highlighted to show that a
connection is needed. E.g. once one of the filter input parameters is mapped, then the
other one is automatically highlighted.
Worksheet names in MS Excel sheets
Example:
When creating a mapping like CompletePO.mfd, available in the ...\MapForceExamples folder, the
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
102
Common Tasks
Working with Connections
inserted XML Schema files exist as shown below.
The Number element of the Customers component is then connected to the Number element of
the CompletePO component. As soon as the connection has been made, the mandatory items/
nodes of the CompletePO component are highlighted. Note that the collapsed "Article" node/icon
is also highlighted.
4.3.2
Changing the Connection Display Preferences
You can selectively view the connections 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.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
Working with Connections
103
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.
4.3.3
Annotating Connections
Individual connections can be labeled allowing you to comment your mapping in great detail. This
option is available for all connection types.
To annotate to a connection:
1.
2.
2.
3.
Note:
Right-click the connection, and select Properties from the context menu.
Enter the name of the currently selected connection in the Description field. This
enables all the options in the Annotation Settings group.
Use the remaining groups to define the starting location, alignment and position of the
label.
Activate the Show annotations
annotation text.
If the Show annotations icon is inactive, you can still see the annotation text if you
place the mouse cursor over the connection. The annotation text will appear in a callout if
the Show tips
4.3.4
icon in the View Options toolbar to see the
toolbar button is active in the View Options toolbar.
Connection Settings
Right-clicking a connection and selecting Properties from the context menu, or double-clicking a
connection, opens the Connection Settings dialog box in which you can define the settings of the
current connection. Note that unavailable options are disabled.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
104
Common Tasks
Working with Connections
Connection Settings dialog b ox
For items of complexType, you can choose one of the following connection types for mapping
(note that these settings also apply to complexType items which do not have any text nodes):
Target Driven
(Standard)
Changes the connection type to "Target-driven" (see Target-driven /
Standard mapping ).
Copy-all (Copy
child items)
Changes the connection type to "Copy-all" and automatically connects all
identical items in the source and target components (see Copy-all
connections ).
Source Driven
(mixed content)
Changes the connection type to "Source-driven", and enables the
selection of additional elements to be mapped. The additional elements
must be child items of the mapped item in the XML source file, to qualify
for mapping.
Activating the Map Processing Instructions or Map Comments check
boxes enables you to include these data groups in the output file.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
Working with Connections
105
Note: CDATA sections are treated as text.
The Annotation Settings group enables you to annotate the connection (see Annotating
Connections ).
4.3.5
Connection Context Menu
When you right-click a connection, the following context commands are available.
Connect matching children
Opens the "Connect Matching Children" dialog box (see
Connecting Matching Children ). This command is enabled
when the connection is eligible to have matching children.
Delete
Deletes the selected connection.
Go to source: <item name>
Selects the source connector of the current connection.
Go to target: <item name>
Selects the target connector of the current connection.
Target Driven (Standard)
Changes the connection type to "Target-driven" (see Targetdriven connections ).
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
106
Common Tasks
Copy-All (Copy Child Items)
Working with Connections
Changes the connection type to "Copy-all" and automatically
connects all identical items in the source and target
components (see Copy-all connections ).
This command is enabled (and meaningful) when both the
source item and the target item have children items.
Source Driven (Mixed Content)
Changes the connection type to "Source-driven" (see Sourcedriven connections ).
This command is enabled (and meaningful) when both the
source item and the target item have children items.
4.3.6
Insert Sort: Nodes/Rows
Adds a Sort component between the source and the target
item (see Sorting Data ).
Insert Filter: Nodes/Rows
Adds a Filter component between the source and the target
item (see Filters and Conditions).
Insert SQL-Where Condition
Adds a SQL-Where component between the source and the
target item (see SQL WHERE / ORDER Component).
Insert Value-Map
Adds a Value-Map component between the source and the
target item (see Using Value-Maps ).
Properties
Opens the Connections Settings dialog box (see Connection
Settings ).
Connecting Matching Children
You can create multiple connections between items of the same name in both the source and
target components. Note that a "Copy-all" connection (see Copy-all connections) is created by
default.
To toggle the "Auto Connect Matching Children" option on or off, do one of the following:
Click the Auto Connect Matching Children (
) toolbar button.
On the Connection menu, click Auto Connect Matching Children.
To change the settings for "Connect Matching Children":
1.
2.
Connect two (parent) items that share identically named child items in both
components.
Right click the connection and select the Connect matching child elements option.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
3.
Note:
Working with Connections
107
Select the required options (see the table below), and click OK. Connections are created
for all the child items that have identical names and adhere to the settings defined in the
dialog box.
The settings you define here are applied when connecting two items if the Toggle auto
connect of children (
) toolbar button is active.
Ignore Case
Ignores the case of the child item names.
Ignore Namespaces
Ignores the namespaces of the child items.
Recursive
Creates new connections between any matching items
recursively. That is, a connection is created no matter how
deep the items are nested in the hierarchy, as long as they
have the same name.
Mix Attributes and Elements
When enabled, allows connections to be created between
attributes and elements which have the same name. For
example, a connection is created if two "Name" items
exist, even though one is an element, and the other is an
attribute.
Create copy-all connections
This setting is active by default. It creates (if possible) a
connection of type "Copy-all" between source and target
items.
Ignore existing output
connections
Creates additional connections for any matching items,
even if they already have outgoing connections.
Retain
Retains existing connections.
Overwrite
Recreates connections according to the settings defined.
Existing connections are discarded.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
108
Common Tasks
Delete all existing
Working with Connections
Deletes all existing connections, before creating new ones.
Deleting connections
Connections that have been created using the Connect Matching Children dialog, or during the
mapping process, can be removed as a group.
To delete connections:
1.
2.
4.3.7
Right-click the item name in the component, not the connection itself ("Person" in this
example).
Select Delete Connections | Delete all ... connections.
Delete all direct connections
Deletes all connections 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 connections.
Delete all outgoing child
connections
Only active if you have right clicked an item in a source
component. Deletes all outgoing child connections.
Notifications on Missing Parent Connections
When you create connections between source and target items manually, MapForce
automatically analyzes the possible mapping outcomes. If you are mapping two child items, a
notification message can appear suggesting that you also connect the parent of the source item
with the parent in the target item.
This notification message helps you prevent situations where a single child item appears in the
Output window when you preview the mapping. This will generally be the case if the source node
supplies a sequence instead of a single value.
To understand how this works, open the sample mapping Tut-OrgChart.mfd available in the
<Documents>\Altova\MapForce2017\MapForceExamples\Tutorial\ folder. If you connect the
source text() item to the target text() item, a notification message appears, stating that the
parent item "para" is not connected and will only be generated once in the output.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
Working with Connections
109
Tut-OrgChart.mfd (MapForce Basic Edition)
To generate multiple para items in the target, connect the source and target para items to each
other.
To disable such notifications, do the following:
1.
2.
3.
4.3.8
On the Tools menu, click Options.
Click the Messages group.
Click to clear the When creating a connection, suggest connecting ancestor items
check box.
Moving Connections and Child Connections
When you move a connection to a different component, MapForce automatically matches
identical child connections and will prompt you whether it should move them to the new location
as well. A common use of this feature is if you have an existing mapping and then change the root
element of the target schema. Normally, when this happens, you would need to remap all
descending connections manually. This feature helps you prevent such situations.
This example uses the Tut-ExpReport.mfd file available in the <Documents>\Altova
\MapForce2017\MapForceExamples\Tutorial\ folder.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
110
Common Tasks
Working with Connections
Tut-ExpReport.mfd (MapForce Basic Edition)
To understand how it works, do the following:
1.
2.
3.
Open the Tut-ExpReport.mfd sample mapping.
Edit the ExpReport-Target.xsd schema outside MapForce so as to change the Company
root element of the target schema to Company-EU. You do not need to close MapForce.
After you have changed the Company root element of the target schema to Company-EU,
a "Changed files" prompt appears in MapForce.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
Working with Connections
4.
Click the Reload button to reload the updated Schema. Since the root element was
deleted, the component displays multiple missing nodes.
5.
Click Select new root element at the top of the component. (You can also change the
root element by right clicking the component header and selecting Change Root
Element from the context menu.)
6.
Select Company-EU as new root element and click OK to confirm. The Company-EU root
element is now visible at the top of the component.
© 2017 Altova Gmb H
111
Altova MapForce 2017 Professional Edition
112
Common Tasks
7.
Working with Connections
Click the target stub of the connection that exists between the expense-report item of
the source component and the Company item of the target component, and then drag-anddrop it on the Company-EU root element of the target component.
A notification dialog box appears.
4.3.9
8.
Click Include descendent connections. This instructs MapForce to re-map the correct
child items under the new root element, and the mapping becomes valid again.
Note:
If the node to which you are mapping has the same name as the source node but is in a
different namespace, then the notification dialog box will contain an additional button:
"Include descendants and map namespace". Clicking this button moves the child
connections of the same namespace as the source parent node to the same child nodes
under the different namespace node.
Keeping Connections After Deleting Components
You can decide what happens when you delete a component that has multiple (child) connections
to another component, e.g. a filter or sort component. This is very useful if you want to keep all
the child connections and not have to restore each one individually.
You can opt to keep/restore the child connections after the component is deleted, or to delete all
child connections immediately.
Select Tools | Options | Editing (tab) to see the current setting. The default setting for the check
box is inactive, i.e. "Smart component deletion (keep useful connections)" is disabled.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
Working with Connections
113
E.g. using the CompletePO.mfd mapping in the ...\MapForceExamples folder, and the check box
is active, the Customer filter is a copy-all connection with many connected child items, as shown
below.
Deleting the Customer filter opens a prompt asking if you really want to delete it. If you select
Yes, then the filter is deleted but all the child connectors remain.
Note that the remaining connectors are still selected (i.e. shown in red). If you want to delete
them as well, hit the Del. key.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
114
Common Tasks
Working with Connections
Clicking anywhere in the mapping area deselects the connectors.
If the "Smart component deletion..." check box is inactive, then deleting the filter will delete all
child connectors immediately.
Note:
4.3.10
If a filter component has both "on-true" and "on-false" outputs connected, then the
connectors for both outputs will be retained.
Dealing with 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.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
Working with Connections
115
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
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.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
116
Common Tasks
Working with Connections
"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, database etc. 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 or database file and prevents preview and code generation.
Placing the mouse cursor over the highlighted component, opens a popup containing pertinent
information.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
Working with Connections
117
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.
Clicking the Change button in the dialog box that opens if the component is a database, allows
you to select a different database, or change the tables that appear in the database component.
Connectors to tables of the same name will be retained.
All valid/correct connections (and relevant database data, if the component is a database) will be
retained if you select a schema or database of the same structure.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
118
4.4
Common Tasks
Working with Mapping Projects
Working with Mapping Projects
In addition to creating standalone mappings, you can also create mapping projects that include
multiple mappings. Mappings added to a project are easily accessible from the Project window.
Project window (MapForce Enterprise Edition)
The main advantage of projects is that you can define common code generation settings (such as
the target language and the output directory) for all the mapping files included in that particular
project. You can also create folders inside projects, and specify custom code generation settings
for each individual folder in a project. For more information about the MapForce-generated program
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
Working with Mapping Projects
119
code (in C++, C#, and Java), see Code Generator.
In MapForce Enterprise edition, you can additionally create Web Service projects. Such projects
enable you to generate Java or C# program code that implements SOAP Web services, based on
existing Web Services Description Language (WSDL) files.
4.4.1
Opening, Searching, and Closing Projects
MapForce project files have the *.mfp extension. You can open existing MapForce projects in the
same way as you open mappings (on the File menu, click Open).
When a mapping project is opened in MapForce, the Project window shows all files and folders
that have been added to the project. By default, when you run MapForce for the first time, it loads
the MapForceExamples.mfp project in the Project window.
To search for files within a project:
1.
2.
3.
In the Project window, click the project or the folder to be searched.
Press Ctrl + F.
Optionally, select your search options. For example, if you want to include folder names
in the search, select the Find in folder names option.
To close a project:
On the Project menu, click Close Project.
4.4.2
Creating a New Project
To create a new project:
1.
2.
On the File menu, click New.
Select Project File, and then click OK.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
120
Common Tasks
3.
Working with Mapping Projects
Enter the project name in the Save Project As dialog box, and click Save. The new
project is now displayed in the Project window.
You can now add mappings to the project.
To add the currently active mapping to the project, do one of the following:
On the Project menu, click Add Active File to Project
.
Right-click the project, and select Add Active File to Project
.
To add existing mapping files to the project, do one of the following:
On the Project menu, click Add Files to Project
.
Right-click the project, and select Add Files to Project
Tip:
.
To open multiple files, hold the Ctrl key while selecting the files in the Open dialog box.
To remove a file or folder from a project, do one of the following:
Right-click the file in the Project window, and select Delete from the context menu.
Select the file in the Project window, and press Delete.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
4.4.3
Working with Mapping Projects
121
Setting the Code Generation Settings
For any project, you can specify code generation settings that will affect all the mappings inside a
project. To open the Project Settings dialog box, do one of the following:
Right-click the project name in the Project window and choose Properties from the
context menu
On the Project menu, click Properties.
Project Settings dialog b ox
The available settings are as follows. Note that the project name and the project directory cannot
be changed after the project has been created.
Output name
The value entered here determines the name of the
generated project or solution, as well as other objects
names in the generated code.
Output directory
Defines the Windows folder where the generated code
(from all mappings in this project) will be saved. By default,
output is saved to the output/ directory located in the
project directory.
Language
Defines the code generation language for all mapping files
in this project.
Base pack age name
This setting is applicable if you selected Java as
transformation language. It defines the name of the base
package in the generated Java project.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
122
4.4.4
Common Tasks
Working with Mapping Projects
Managing Project Folders
If you want to organize the mappings inside a project into folders, you can create as many folders
as required, and add mappings to (or drag mappings into) them. Such folders are "virtual" and
meaningful only inside a MapForce project; they do not correspond to actual folders on your
operating system. One of the advantages of creating folders is that you can define common code
generation settings (such as the target language and the output directory) for all the mapping files
under that particular folder.
Folder Properties dialog b ox
To create a folder inside a MapForce project:
1.
Do one of the following:
o
2.
On the Project menu, click Create Folder
.
o Right-click the project, and select Create Folder
.
In the Properties dialog box, enter the required code generation settings, and click OK.
The settings you can define in the Folder Properties dialog box are as follows.
Name
The name of the folder.
Use default project settings
This is the default option and it means that the code
generation settings in the current folder are the same as for
the entire project. Therefore, when you generate code from
you project, MapForce will use the code generation
settings defined at the project level, not at the folder level.
If your folder requires custom code generation settings
(other than those set at the project level), select Use the
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Common Tasks
Working with Mapping Projects
123
following settings and specify the code output directory
and language as required.
Output directory
Defines the Windows folder where the generated code
(from all mappings in this folder) will be saved.
Language
Defines the code generation language for all mapping files
in this folder.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
Chapter 5
Designing Mappings
126
Designing Mappings
5
Designing Mappings
This section describes how to design data mappings, and ways in which you can transform data
on the mapping area. It also includes various considerations applicable to mapping design. Use
the following roadmap for quick access to specific tasks or concepts:
I want to...
Read this topic...
Create or edit path references to
miscellaneous schema, instance, and other
files used by a mapping.
Using Relative and Absolute Paths
Fine-tune the data mapping for specific needs
(for example, influence the sequence of items
in a target component).
Connection Types
Use the output of a component as input of
another component.
Chained mappings / pass-through components
Process multiple files (for example, all files
within a directory) in the same mapping, either
as a source or a target.
Processing Multiple Input or Output Files
Dynamically
Pass an external value (such as a string
parameter) to the mapping.
Supplying Parameters to the Mapping
Get a string value out of the mapping, instead
of a file.
Returning String Values from a Mapping
Store some mapping data temporarily for later
processing (similar to variables in a
programming language).
Using Variables
Sort data in ascending or descending order.
Sorting Data
Filter nodes/rows based on specific criteria, or
process values conditionally.
Filters and Conditions
Merge or join data from multiple sources with
different schema.
Joining Data
Merging Data from Multiple Schemas
Process key-value pairs, for example, to
convert months from numerical representation
(01, 02, and so on) to text representation
(January, February, and so on).
Using Value-Maps
Configure a mapping to return an error when a
specific condition occurs.
Adding Exceptions
Learn how to avoid undesired results when
designing complex mappings.
Mapping rules and strategies
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
127
Importantly, MapForce additionally includes an extensive built-in function library (see Function
Library Reference) to help you with a wide array of processing tasks. When the built-in library is
not sufficient, you can always build your own custom functions in MapForce, or re-use external
XSLT files, as well as .dll or Java .class libraries. For further information, see Using Functions.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
128
5.1
Designing Mappings
Using Relative and Absolute Paths
Using Relative and Absolute Paths
A mapping design file (*.mfd) may have references to several schema and instance files. The
schema files are used by MapForce to determine the structure of the data to be mapped, and to
validate it. The instance files, on the other hand, are required to read, preview, and validate the
source data against the schema.
Mappings may also include references to StyleVision Power Stylesheets (*.sps) files, used to
format data for outputs such as PDF, HTML and Word. Also, mappings may have references to
file-based databases such as Microsoft Access or SQLite.
All references to files used by a mapping design are created by MapForce when you add a
component to the mapping. However, you can always set or change such path references
manually if required.
This section provides instructions for setting or changing the path to miscellaneous file types
referenced by a mapping, and the implications of using relative versus absolute paths.
5.1.1
Using Relative Paths on a Component
The Component Settings dialog box (illustrated below for an XML component) provides the option
to specify either absolute or relative paths for various files which may be referenced by the
component:
Input files (that is, files from which MapForce reads data)
Output files (that is, files to which MapForce writes data)
Schema files (applicable to components which have a schema)
Structure files (applicable to components which may have a complex structure, such as
input or output parameters of user-defined functions, or variables)
StyleVision Power Stylesheet (*.sps) files, used to format data for outputs such as PDF,
HTML and Word.
You can enter relative paths directly in the relevant text boxes (shown enclosed in a red frame in
the image below).
Before entering relative file paths, make sure to save the mapping file (.mfd) first. Otherwise,
all relative paths are resolved against the personal application folder of Windows (Documents
\Altova\MapForce2017), which may not be the intended behavior.
You can also instruct MapForce to save all above-mentioned file paths relative to the mapping
.mfd file. In the sample image below, notice the option Save all file paths relative to MFD file.
If the check box is enabled (which is the default and recommended option), the paths of any files
referenced by the component will be saved relative to the path of the mapping design file (.mfd).
This affects all files referenced by the component (shown enclosed in a red frame in the image).
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Using Relative and Absolute Paths
129
Component Settings dialog b ox
Although the component illustrated above is an XML component, the setting Save all file paths
relative to MFD file works in the same way for the following files:
Structure files used by complex input or output parameters of user-defined functions and
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
130
Designing Mappings
Using Relative and Absolute Paths
variables of complex type
Input or output flat files *
Schema files referenced by database components which support XML fields *
Input or output XBRL, FlexText, EDI, Excel 2007+, JSON files **
* MapForce Professional and Enterprise Edition
** MapForce Enterprise Edition only
Taking the component above as an example, if the .mfd file is in the same folder as the
books.xsd and books.xml files, the paths will be changed as follows:
C:\Users\altova\Documents\MyMapping\books.xsd will change to books.xsd
C:\Users\altova\Documents\MyMapping\books.xml will change to books.xml
Paths that reference a non-local drive or use a URL will not be made relative.
When the check box is enabled, MapForce will also keep track of the files referenced by the
component if you save the mapping to a new folder using the Save as menu command. Also, if all
files are in the same directory as the mapping, path references will not be broken when you move
the entire directory to a new location on the disk.
Using relative paths (and, therefore, enabling the Save all file paths relative to MFD file check
box) may be important in many cases, for example:
The location of the mapping on your operating system is likely to change in future.
The mapping is stored in a directory which is under source control (using a version control
system such as TortoiseSVN, for example).
You intend to deploy the mapping for execution to a different machine or even to a
different operating system.
If the Save all file paths relative to MFD file check box is disabled, saving the mapping does
not modify the file paths (that is, they remain as they appear in the Component Settings dialog
box).
5.1.2
Setting the Path to File-Based Databases
When you add a database file such as Microsoft Access or SQLite to the mapping (see Starting
the Database Connection Wizard ), you can use a relative path instead of an absolute one. To use
a relative path, enter the required relative path instead of clicking Browse in the Database
Connection Wizard.
Before entering relative file paths, make sure to save the mapping file (.mfd) first. Otherwise,
all relative paths are resolved against the personal application folder of Windows (Documents
\Altova\MapForce2017), which may not be the intended behavior.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Using Relative and Absolute Paths
131
Datab ase Connection Wizard
If the database is a SQLite database, the Connect button becomes enabled if the following is
true:
The path points to a file that can be resolved relatively to the mapping (.mfd) file
The referenced file is a SQLite database.
To change the path of a database component which is already in the mapping, do the following:
1.
2.
Right-click the header of the database component, and select Properties (see also
Changing the Component Settings). Alternatively, double-click the component title bar.
On the Component Settings dialog box, click Change.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
132
Designing Mappings
Using Relative and Absolute Paths
This re-opens the Database Connection Wizard, from where you can change the database
connection properties (including the path) as already shown above.
Note that “Connection String” always contains an absolute path. It is the database which is used
for the structure information in the component. The relative path in “Data Source” indicates that
the component was created with a relative file path.
When you generate code, or when you compile MapForce Server execution files (.mfx), the path
of the database will be absolute or relative, depending on the mapping settings (see About Paths
in Generated Code).
5.1.3
Fixing Broken Path References
When you add or change a file reference in a mapping, and the path cannot be resolved,
MapForce displays a warning message. This way, MapForce diminishes the chance for broken
path references to happen. Nevertheless, broken path references may still occur in cases such
as:
You use relative paths, and then move the mapping file to a new directory without moving
the schema and instance files.
You use absolute paths to files in the same directory as the mapping file, and then move
the directory to another location.
When this happens, MapForce highlights the component in red, for example:
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Using Relative and Absolute Paths
133
Broken path reference
The solution in this case is to double-click the component header and update any broken path
references in the Component Settings dialog box (see also Changing the Component Settings ).
5.1.4
About Paths in Generated Code
If you generate code from mappings, or if you compile mappings to MapForce Server execution
files (.mfx), the generated files will no longer be run by MapForce, but by the target environment
you have chosen (for example, RaptorXML Server, MapForce Server, or a C# application). The
implication is that, for the mapping to run successfully, any relative paths must be meaningful in
the environment where the mapping runs.
Consequently, when the mapping uses relative paths to instance or schema files, consider the
base path to be as follows for each target language:
Target language
Base path
XSLT/XSLT2
Path of the XSLT file.
XQuery*
Path of the XQuery file.
C++, C#, Java*
Working directory of the generated
application.
BUILT-IN* (when previewing the mapping in
MapForce)
Path of the mapping (.mfd) file.
BUILT-IN* (when running the mapping with MapForce
Server)
The current working directory.
BUILT-IN* (when running the mapping with MapForce
Server under FlowForce Server control)
The working directory of the job or the
working directory of FlowForce Server.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
134
Designing Mappings
Using Relative and Absolute Paths
* Languages availab le in MapForce Professional and Enterprise editions
If required, you can instruct MapForce to convert all paths from relative to absolute when
generating code for a mapping. This option might be useful if you run the mapping code (or the
MapForce Server execution file) on the same operating system, or perhaps on another operating
system where any absolute path references used by the mapping can still be resolved.
To convert all paths to absolute in the generated code, select the Make paths absolute in
generated code check box, on the Mapping Settings dialog box (see Changing the Mapping
Settings ).
When you generate code and the check box is selected, MapForce resolves any relative paths
based on the directory of the mapping file (.mfd), and makes them absolute in the generated
code. This setting affects the path of the following files:
Input and output instance files for all file-based component kinds
Access and SQLite database files used as mapping components
When the check box is not selected, the file paths will be written in the generated code as they
are defined in the component settings.
5.1.5
Copy-Paste and Relative Paths
When you copy a component from a mapping and paste it into another, a check is performed to
ensure that relative paths of schema files can be resolved against the folder of the destination
mapping. If the path cannot be resolved, you will be prompted to make the relative paths absolute
by means of the folder of the source mapping. It is recommended to save the destination mapping
first, otherwise relative paths are resolved against the personal application folder.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
5.2
Connection Types
135
Connection Types
When you create a mapping connection (and both the source and the target item have child
items), you can optionally choose the type of the connection to be one of the following.
Target Driven (Standard)
Source Driven (Mixed Content)
Copy-All (Copy Child Items).
The connection type determines the sequence of children items in the output generated by the
mapping. This section provides information about each connection type and the scenarios when
they are useful.
5.2.1
Target-driven connections
When a connection is "target-driven" (or "standard"), the sequence of child nodes in the mapping
output is determined by the sequence of nodes in the target schema. This connection type is
suitable for most mapping scenarios and is the default connection type used in MapForce.
On a mapping, target-driven connections are shown with a solid line.
Target-driven connections might not be suitable when you want to map XML nodes that contain
mixed context (character data as well as child elements), for example:
<p>This is our <i>best-selling</i> product.</p>
With mixed content, it is likely that you want to preserve the sequence of items as they appear in
the source file, in which case a source-driven connection is recommended (see Source-driven
connections ).
5.2.2
Source-driven connections
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.
Mixed content text node content is supported/mapped.
The sequence of child nodes is dependent on the source XML instance file.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
136
Designing Mappings
Connection Types
Mixed content mappings are shown with a dotted line.
Source-driven / mixed content 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:
Mappings from
As source components:
– XML schema complexTypes (including mixed content, i.e. mixed=true)
– XML schema complexTypes (including mixed content) in embedded schemas of a
database field
As target components:
– XML schema complexTypes (including mixed content),
– XML schema complexTypes (including mixed content) in embedded schemas of a
database field
Note: CDATA sections are treated as text.
5.2.2.1
Mapping mixed content
The files used in the following example (Tut-OrgChart.mfd, Tut-OrgChart.mfd.xml, TutOrgChart.mfd.xsd, Tut-Person.xsd) are available in the ...\MapForceExamples\Tutorial\
folder.
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 its child nodes "bold" and "italic".
The para element also contains a Processing Instruction (<?sort alpha-ascending?>) as well
as Comment text (<!--Company details... -->) which can also be mapped, as shown below.
Please note the sequence of the text and bold/italic nodes of Nanonull., Inc in the XML instance
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Connection Types
137
file, they are:
<para> The company...
<bold>Vereno</bold>in 1995 ...
<italic>multi-core...</italic>February 1999
<bold>Nano-grid.</bold>The company ...
<italic>offshore...</italic>to drive...
</para>
Initial mapping
The initial state of the mapping when you open Tut-Orgchart.mfd 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.
Mapping the para element
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.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
138
Designing Mappings
Connection Types
To annotate (add a label to) any connection, right-click it and select Properties (see Annotating
Connections ).
The image below shows the content model of the Description element (Desc) of the TutOrgChart.xsd schema file. This definition is identical in both the source and target schemas used
in this example.
Note the following properties of the para element in the Content model:
para is a complexType with mixed="true", of type "TextType"
bold and italic elements are both of type "xs: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.
To create mixed content connections between items:
1.
2.
Select the menu option Connection | Auto Connect Matching Children to activate this
option, if it is not currently activated.
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 mixedcontent message also appears if you only map the para items directly, without having the
autoconnect option activated.
4.
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.
Click the Output tab to see the result of the mapping.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
5. Click the word Wrap icon
Output window.
6.
Connection Types
139
in the Output tab icon bar, to view the complete text in the
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.
Switch back to the Mapping view.
To remove text nodes from mixed content items:
1.
Click the text() node connector and press Del. to delete it.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
140
Designing Mappings
2.
Connection Types
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.
To map the Processing Instructions and Comments:
1.
2.
5.2.2.2
Right-click the mixed content connection, and select Properties.
Under Source-Drive (Mixed content), select the Map Processing Instructions and
Map Comments check boxes.
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.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Connection Types
141
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.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
142
5.2.2.3
Designing Mappings
Connection Types
Using standard connections on mixed content items
As mentioned before, source-driven (not standard) connections are normally used when mapping
data from mixed content nodes. Otherwise, the resulting output may be undesirable. To see the
consequences of using a standard (target-driven) connection when mapping data from a mixed
content node, follow the steps below:
1.
2.
Note:
3.
Open the mapping Tut-OrgChart.mfd from the <Documents>\Altova\MapForce2017
\MapForceExamples\Tutorial\ folder.
Create a connection between the para node in the source and the para node in the
target. A message appears, asking if you would like MapForce to define the connections
as source-driven. Click No (this disregards the MapForce suggestion and creates a
standard connection).
Make sure that the connection is standard (target-driven), as shown above. If a Copy-All
connection is created automatically, right-click the connection, and select Target Driven
(Standard) from the context menu.
Click the Output tab to see the result of the mapping.
As illustrated above, mapping mixed content nodes using standard connections produces the
following result:
The content of the text() source item is copied to the target; however, the sequence of
child nodes (bold and italic, in this case) in the output corresponds to the sequence in
the target XML schema. In other words, the child nodes (bold and italic, in this case)
appear after the mixed content node text.
For each para element, MapForce has mapped the text() node first, then all bold
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Connection Types
143
items, and, finally, all italic items. As a result, multiple bold and italic items appear
stacked on each other. Note that the content of each item is mapped if a connection
exists to it from the source.
5.2.3
Copy-All Connections
Copy-All connections map data between complex structures (nodes with children items) that are
very similar or identical. The main benefit of "Copy-All" connections is that they simplify the
mapping workspace (one "thick" connection is created instead of multiple).
On the mapping, a "Copy-All" connection appears as a single bold line (with input and output
"forks" for each child item) that connects two identical or similar structures.
Copy-All connection
When you draw a mapping connection between two structures on the mapping, MapForce creates
a "Copy-All" connection automatically if it detects that the source and target structure are
assignment compatible (that is, when both structures are either of the same type, or the target is
a subtype of the source type). At mapping runtime, all instance data will be copied from the
source to the target recursively, including children.
To create a "Copy-All" connection manually, right-click an existing connection between two
similar nodes with child items, and select Copy-All (Copy Child Items) from the context menu.
Note the following:
In contexts where a "Copy-All" connection is not meaningful or not supported, it is not
possible to create this kind of connection manually.
A "Copy-All" connection cannot be created to the root element of an XML/Schema
component.
When creating "Copy-All" connections between a schema and a parameter of a userdefined function, the two components must be based on the same schema. It is not
necessary that they both have the same root elements, however.
For an example of a "Copy-All" connection created manually, take the following steps:
1.
2.
3.
4.
Create a new mapping.
On the Insert menu, click XML Schema/File and browse for the books.xml file located
in the folder <Documents>\Altova\MapForce2017\MapForceExamples\Tutorial\.
On the Insert menu, click XML Schema/File and browse for the library.xsd file located
in the folder <Documents>\Altova\MapForce2017\MapForceExamples\Tutorial\.
Draw a mapping connection between the book node of the "books" component to the
publication node of the "library" component.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
144
Designing Mappings
5.
Connection Types
Right-click the new connection, and select Copy-All (Copy Child Items) from the
context menu.
If there are slight differences between the source and the target structures, the "Copy-All"
connection will enumerate, at mapping runtime, the source items (such as elements and
attributes) and will copy only those that exist in the target type. This is repeated recursively.
For example, in the mapping above, only two child items are identical between the two structures
(author and title) and thus they are mapped to the target. The item id is not included
automatically because it is an attribute in the source and an element in the target. If you need to
map, for example, category to genre, the "Copy-All" connection is no longer possible, because
these are different items.
When an input connector (the small triangle to the side of the component) receives a "Copy-All"
connection, it cannot accept any other connections. In the example above, if you attempt to
create a connection between category and genre, MapForce prompts you to either replace it, or
duplicate the input.
Duplicating input is meaningful only if you want the target to accept data from more than one
input, which is not required here (see also Duplicating Input). If you choose to replace the "CopyAll" connection, a message box prompts you again to either resolve or delete the "Copy-All"
connection.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Connection Types
145
Click Resolve copy-all connection if you want to replace the "Copy-All" connection by standard
individual target-driven connections to corresponding child items. If you prefer to remove the
"Copy-All" connection completely, click Delete child connections.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
146
5.3
Designing Mappings
Chained Mappings
Chained Mappings
MapForce supports mappings that consist of multiple components in a mapping chain. Chained
mappings are mappings where at least one component acts both as a source and a target. Such
a component creates output which is later used as input for a following mapping step in the chain.
Such a component is called an "intermediate" component.
For example, the mapping illustrated below shows an expense report (in XML format) that is being
processed in two stages. The part of the mapping from A to B filters out only those expenses that
are marked as "Travel". The mapping from B to C filters out only those "Travel" expenses that
have a travel cost less than 1500. Component B is the "intermediate" component, as it has both
input and output connections. This mapping is available at the following path: <Documents>
\Altova\MapForce2017\MapForceExamples\Tutorial\ChainedReports.mfd.
ChainedReports.mfd
Chained mappings introduce a feature called "pass-through". "Pass-through" is a preview
capability allowing you to view the output produced at each stage of a chained mapping in the
Output window. For example, in the mapping above, you can preview and save the XML output
resulting from A to B, as well as the XML output resulting from B to C.
Note:
The "pass-through" feature is available only for file-based components (for example, XML,
CSV, and text). Database components can be intermediate, but the pass-through button
is not shown. The intermediate component is always regenerated from scratch when
previewing or generating code. This would not be feasible with a database as it would
have to be deleted prior to each regeneration.
If the mapping is executed by MapForce Server, or by generated code, then the full mapping chain
is executed. The mapping generates the necessary output files at each step in the chain, and the
output of a step of a mapping chain is forwarded as input to the following mapping step.
It is also possible for intermediate components to generate dynamic file names. That is, they can
accept connections to the "File:" item from the mapping, provided that the component is
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Chained Mappings
147
configured correspondingly. For more information, see Processing Multiple Input or Output Files
Dynamically.
Preview button
Both the component B and the component C have preview buttons. This allows you to preview in
MapForce the intermediate mapping result of B, as well as the final result of the chained mapping.
Click the preview button of the respective component, then click Output to see the mapping result.
"Intermediate" components with the pass-through button active cannot be previewed. Their preview
button is automatically disabled, because it is not meaningful to preview and let data pass through
at the same time. To see the output of such a component, first click the "pass-through" button to
deactivate it, and then click the preview button.
Pass-through button
The intermediate component B has an extra button in the component title bar called "passthrough".
If the pass-through button is active
, MapForce maps all data into the preview window in one
go; from component A to component B, then on to component C. Two result files will be created:
the result of mapping component A to intermediate component B
the result of the mapping from the intermediate component B, to target component C.
If the pass-through button is inactive
, MapForce will execute only parts of the full mapping
chain. Data is generated depending on which preview buttons are active:
If the preview button of component B is active, then the result of mapping component A to
component B is generated. The mapping chain actually stops at component B.
Component C is not involved in the preview at all.
If the preview button of component C is active, then the result of mapping intermediate
component B to the component C is generated. Because pass-through is inactive,
automatic chaining has been interrupted for component B. Only the right part of the
mapping chain is executed. Component A is not used.
When the "pass-through" button is inactive, it is important that the intermediate component
has identical file names in the "Input XML File" and "Output XML File" fields. This ensures
that the file generated as output when you preview the portion of the mapping between A and
B is used as input when you preview the portion of the mapping between B and C. Also, in
generated code, or in MapForce Server execution, this ensures that the mapping chain is not
broken.
As previously mentioned, if the mapping is executed by MapForce Server, or by generated code,
then the output of all components is generated. In this case, the settings of the pass-through
button of component B, as well as the currently selected preview component, are disregarded.
Taking the mapping above as example, two result files will be generated, as follows:
1.
2.
The output file resulting from mapping component A to B
The output file resulting from mapping component B to C.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
148
Designing Mappings
Chained Mappings
The following sections, Example: Pass-Through Active and Example: Pass-Through Inactive,
illustrate in more detail how the source data is transferred differently when the pass-through button
is active or inactive.
5.3.1
Example: Pass-Through Active
The mapping used in this example (ChainedReports.mfd) is available in the <Documents>
\Altova\MapForce2017\MapForceExamples\Tutorial\ folder. This mapping processes an XML
file called ReportA.xml that contains travel expenses and looks as shown below. For simplicity,
the namespace declaration and some expense-item elements have been omitted:
<?xml version="1.0" encoding="UTF-8"?>
<expense-report currency="USD" detailed="true">
<Person>
<First>Fred</First>
<Last>Landis</Last>
<Title>Project Manager</Title>
<Phone>123-456-78</Phone>
<Email>f.landis@nanonull.com</Email>
</Person>
<expense-item type="Travel" expto="Development">
<Date>2003-01-02</Date>
<Travel Trav-cost="337.88">
<Destination/>
</Travel>
<description>Biz jet</description>
</expense-item>
<expense-item type="Lodging" expto="Sales">
<Date>2003-01-01</Date>
<Lodging Lodge-cost="121.2">
<Location/>
</Lodging>
<description>Motel mania</description>
</expense-item>
<expense-item type="Travel" expto="Marketing">
<Date>2003-02-02</Date>
<Travel Trav-cost="2000">
<Destination/>
</Travel>
<description>Hong Kong</description>
</expense-item>
</expense-report>
ReportA.xml
The goal of the mapping it to produce, based on the file above, two further reports:
ReportB.xml - this report should contain only those travel expenses that are of type
"Travel".
ReportC.xml - this report should contain only those travel expenses that are of type
"Travel" and do not exceed 1500.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Chained Mappings
149
To achieve this goal, the intermediate component of the mapping (component B) has the passthrough button
active, as shown below. This causes the mapping to be executed in stages:
from A to B, and then from B to C. The output created by the intermediate component will be used
as input for the mapping between B and C.
The names of generated output files at each stage in the mapping chain is determined by the
settings of each component. (To open the component settings, right-click it, and then select
Properties from the context menu). Namely, the first component is configured to read data from
an XML file called ReportA.xml. Because this is a source component, the Output XML File field
is irrelevant and it was left empty.
Settings of the source component
As shown below, the second component (ReportB) is configured to create an output file called
ReportB.xml. Notice that the Input XML File field is grayed out. When pass-through is active
(as in this example), the Input XML File field of the intermediate component is automatically
deactivated. An input file name need not exist for the mapping to execute, because the output
created at this stage in the mapping is stored in a temporary file and reused further in the
mapping. Also, if an Output XML File is defined (as illustrated below), then it is used for the file
name of the intermediate output file. If no Output XML File is defined, a default file name will be
automatically used.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
150
Designing Mappings
Chained Mappings
Settings of the intermediate component
Finally, the third component is configured to produce an output file called ReportC.xml. The
Input XML File field is irrelevant here, because this is a target component.
Settings of the target component
If you preview the mapping by clicking the Output tab in the mapping window, two files are shown
in the output, as expected:
1.
2.
ReportB.xml, which represents the result of the mapping A to B
ReportC.xml, which represents the result of mapping B to C.
To select which of the two generated output files should be displayed in the Output window, either
click the arrow buttons, or select the desired entry from the dropdown list.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Chained Mappings
151
Generated output files
When the mapping is executed by MapForce, the setting "Write directly to final output
file" (configured from Tools | Options | General) determines whether the intermediate files are
saved as temporary files or as physical files. Note that this is only valid when the mapping is
previewed directly in MapForce. Had this mapping been executed by MapForce Server or by
generated code, actual files would be produced at each stage in the mapping chain.
If StyleVision is installed, and if a StyleVision Power Stylesheet (SPS) file has been assigned to
the target component (as in this example), then the final mapping output can be viewed (and
saved as) HTML, RTF file. To generate and view this output in MapForce, click the tab with the
corresponding name.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
152
Designing Mappings
Chained Mappings
Generated HTML output
Note that only the output of the final target component in the mapping chain is displayed. To
display StyleVision output of intermediary components, you would need to deactivate the passthrough button, and preview the intermediate component (as shown in Example: Pass-Through
Inactive ).
5.3.2
Example: Pass-Through Inactive
The mapping used in this example (ChainedReports.mfd) is available in the <Documents>
\Altova\MapForce2017\MapForceExamples\Tutorial\ folder. This example illustrates how
output is generated differently when the pass-through button
is deactivated on the
intermediate component.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Chained Mappings
153
As explained in Example: Pass-Through Active, the goal of the mapping is to produce two
separate reports. In the previous example, the pass-through button was active
, and both
reports were generated as expected and could be viewed in the Output tab. However, if you want
to preview only one of the reports (either ReportB.xml or ReportC.xml), then the pass-through
button must be deactivated (
). More precisely, deactivating the pass-through button may be
useful if you want to achieve the following:
Preview only output generated from A to B, and disregard the portion of the mapping from
B to C
Preview only output generated from B to C, and disregard the portion of the mapping from
A to B.
When you deactivate the pass-through button as shown above, you can choose whether to
preview either ReportB or ReportC (notice that both have preview
buttons).
Deactivating the pass-through button also lets you to choose what input file should be read by the
intermediate component. In most cases, this should be the same file as defined in Output XML
File field (as in this example).
Settings of the intermediate component
Having the same input and output file on the intermediate component is particularly important if
you intend to generate code from the mapping, or run the mapping with MapForce Server. As
previously mentioned, in these environments, all outputs created by each component in the
mapping chain are generated. So, it usually makes sense for the intermediate component to
receive one file for processing (in this case ReportB.xml) and forward the same file to the
subsequent mapping, rather than look for a different file name. Be aware that, not having the same
input and output file names on the intermediate component (when the pass-through button is
inactive) might cause errors such as "The system cannot find the file specified" in generated code
or in MapForce Server execution.
If you click the preview button
on the third component (ReportC), and attempt to preview the
mapping in MapForce, you will notice that an execution error occurs. This is expected, since,
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
154
Designing Mappings
Chained Mappings
according to the settings above, a file called ReportB.xml is expected as input. However, the
mapping did not produce yet such a file (because the pass-through button is not active, and only
the portion of the mapping from B to C is executed). You can easily fix this problem as follows:
1.
2.
3.
Click the preview button on the intermediate component.
Click the Output tab to preview the mapping.
Save the resulting output file as ReportB.xml, in the same folder as the mapping
(<Documents>\Altova\MapForce2017\MapForceExamples\Tutorial\).
Now, if you click again the preview button on the third component (ReportC), the error is no longer
shown.
When the pass-through button is inactive, you can also preview the StyleVision-generated output
for each component that has an associated StyleVision Power StyleSheet (SPS) file. In
particular, you can view the HTML version of the intermediate report as well (in addition to that of
the final report):
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Chained Mappings
155
HTML output of the intermediate component
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
156
5.4
Designing Mappings
Processing Multiple Input or Output Files Dynamically
Processing Multiple Input or Output Files Dynamically
You can configure MapForce to process multiple files (for example, all files in a directory) when
the mapping runs. Using this feature, you can solve tasks such as:
Supply to the mapping a list of input files to be processed
Generate as mapping output a list of files instead of a single output file
Generate a mapping application where both the input and output file names are defined at
runtime
Convert a set of files to another format
Split a large file (or database) into smaller parts
Merge multiple files into one large file (or load them into a database)
You can configure a MapForce component to process multiple files in one of the following ways:
Supply the path to the required input or output file(s) using wildcard characters instead of
a fixed file name, in the component settings (see Changing the Component Settings).
Namely, you can enter the wildcards * and ? in the Component Settings dialog box, so
that MapForce resolves the corresponding path when the mapping runs.
Connect to the root node of a component a sequence which supplies the path
dynamically (for example, the result of the replace-fileext function). When the
mapping runs, MapForce will read dynamically all the input files or generate dynamically
all the output files.
Depending on what you want to achieve, you can use either one or both of these approaches on
the same mapping. However, it is not meaningful to use both approaches at the same time on the
same component. To instruct MapForce which approach you want to use for a particular
component, click the File (
) or File/String (
) button available next to the root
node of a component. This button enables you to specify the following behavior:
Use File Names from Component
Settings
If the component should process one or several
instance files, this option instructs MapForce to
process the file name(s) defined in the Component
Settings dialog box.
If you select this option, the root node does not
have an input connector, as it is not meaningful.
If you did not specify yet any input or output files in
the Component Settings dialog box, the name of
the root node is File: (default). Otherwise, the root
node displays the name of the input file, followed by
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Processing Multiple Input or Output Files Dynamically
157
a semi-colon ( ;), followed by the name of the
output file.
If the name of the input is the same with that of the
output file, it is displayed as name of the root node.
Note that you can select either this option or the
Use Dynamic File Names Supplied by Mapping
option.
Use Dynamic File Names Supplied by
Mapping
This option instructs MapForce to process the file
name(s) that you define on the mapping area, by
connecting values to the root node of the
component.
If you select this option, the root node gets an input
connector to which you can connect values that
supply dynamically the file names to be processed
during mapping execution. If you have defined file
names in the Component Settings dialog box as
well, those values are ignored.
When this option is selected, the name of the root
node is displayed as File: <dynamic>.
This option is mutually exclusive with the Use File
Names from Component Settings option.
Parse Strings to XML, Parse Strings to
JSON, Parse Strings to CSV, Parse
Strings to FLF, Parse Strings to EDI
When switched on, this option enables the
component to accept a string value as input to the
root node, and convert it to an XML, JSON, CSV,
FLF, or EDI structure, respectively. For more
information, see Parsing and Serializing Strings.
Serialize XML to Strings, Serialize JSON
to Strings, Serialize CSV to Strings,
When switched on, this option enables the
component to accept a structure as input, and
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
158
Designing Mappings
Processing Multiple Input or Output Files Dynamically
Serialize FLF to Strings, Serialize EDI to
Strings
convert it to string. The input structure can be XML,
JSON, CSV, Fixed-length Field, or EDI,
respectively. For more information, see Parsing and
Serializing Strings.
Multiple input or output files can be defined for the following components:
XML files
Text files (CSV*, FLF* files and FlexText** files)
EDI documents**
Excel spreadsheets**
XBRL documents**
* Requires MapForce Professional Edition
** Requires MapForce Enterprise Edition
The following table illustrates support for dynamic input and output file and wildcards in MapForce
languages.
Target
language
Dynamic input
file name
Wildcard support for
input file name
Dynamic output file
name
XSLT 1.0
*
Not supported by XSLT 1.0
Not supported by XSLT
1.0
XSLT 2.0
*
*(1)
*
XQuery
*
*(1)
Not supported by
XQuery
C++
*
*
*
C#
*
*
*
Java
*
*
*
BUILT-IN
*
*
*
Legend:
5.4.1
*
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. For details on
how to transform XSLT 1.0/2.0 and XQuery code using the RaptorXML Server engine, see
Generating XSLT 1.0, or 2.0 code and Generating XQuery 1.0 code.
Mapping Multiple Input Files to a Single Output File
To process multiple input files, do one of the following:
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Processing Multiple Input or Output Files Dynamically
159
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 supply as mapping input all files whose name begins with
"Nanonull-". Multiple input files are being merged into a single output file because there
is no dynamic connector to the target component, while the source component accesses
multiple files using the wildcard *. Notice that the name of the root node in the target
component is File: <default>, indicating that no output file path has been defined in the
Component Settings dialog box. The multiple source files are thus appended in the target
document.
MergeMultipleFiles.mfd (MapForce Basic Edition)
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 components such
as an XML file , database text fields.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
160
Designing Mappings
Processing Multiple Input or Output Files Dynamically
MergeMultipleFiles_List.mfd (MapForce Basic Edition)
5.4.2
Mapping Multiple Input Files to Multiple Output Files
To map multiple files 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.
In the following mapping, the output file name is derived from the input file name, by adding the
prefix "Persons-" with the help of the concat function.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Processing Multiple Input or Output Files Dynamically
161
MultipleInputToMultipleOutputFiles.mfd (MapForce Basic Edition)
Note:
Avoid simply connecting the input and output root nodes directly, without using any
processing functions. Doing this will overwrite your input files when you run the mapping.
You can change the output file names using functions such as the concat function, as
shown above.
The menu option File | Mapping Settings allows you to define globally the file path settings used
by the mapping (see Changing the mapping settings).
5.4.3
Supplying File Names as Mapping Parameters
To supply custom file names as input parameters to the mapping, do the following:
1.
1.
2.
Add an Input component to the mapping (On the Function menu, click Insert Input). For
more information about such components, see Simple Input.
Click the File (
) or File/String (
) button of the source component and
select Use Dynamic File Names Supplied by Mapping.
Connect the Input component to the root node of the component which acts as mapping
source.
For a worked example, see Example: Using File Names as Mapping Parameters.
5.4.4
Previewing Multiple Output Files
Click the Output tab to display the mapping result in a preview window. If the mapping produces
multiple output files, each file has its own numbered pane in the Output tab. Click the arrow
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
162
Designing Mappings
Processing Multiple Input or Output Files Dynamically
buttons to see the individual output files.
MultipleInputToMultipleOutputFiles.mfd
To save the generated output files, do one of the following:
On the Output menu, click Save All Output Files (
).
Click the Save all generated outputs (
) toolbar button.
5.4.5
Example: Split One XML File into Many
This example shows you how to generate dynamically multiple XML files from a single source
XML file. The accompanying mapping for this example is available at the following path:
<Documents>\Altova\MapForce2017\MapForceExamples\Tutorial\Tut-ExpReport-dyn.mfd.
The source XML file (available in the same folder as the mapping) consists of the expense report
for a person called "Fred Landis" and contains five expense items of different types. The aim of
the example is to generate a separate XML file for each of the expense items listed below.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Processing Multiple Input or Output Files Dynamically
163
mf-ExpReport.xml (as shown in XMLSpy Grid view)
As the type attribute defines the specific expense item type, this is the item we will use to split
up the source file. To achieve the goal of this example, do the following:
1.
2.
3.
1.
4.
Insert a concat function (you can drag it from the core | string functions library of the
Libraries pane).
Insert a constant (on the Insert menu, click Constant) and enter ".xml" as its value.
Insert the auto-number function (you can drag it from the core | generator functions
library of the Libraries pane).
Click the File (
) or File/String (
) button of the target component and
select Use Dynamic File Names Supplied by Mapping.
Create the connections as shown below and then click the Output tab to see the result of
the mapping.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
164
Designing Mappings
Processing Multiple Input or Output Files Dynamically
Tut-ExpReport-dyn.mfd (MapForce Basic Edition)
Note that the resulting output files are named dynamically as follows:
The type attribute supplies the first part of the file name (for example, "Travel").
The auto-number function supplies the sequential number of the file (for example,
"Travel1", "Travel2", and so on).
The constant supplies the file extension, which is ".xml", thus "Travel1.xml" is the file
name of the first file.
5.4.6
Example: Split Database Table into Many XML Files
This example shows you how to generate dynamically multiple XML files, one for each record of a
database table. The accompanying mapping for this example is available at the following path:
<Documents>\Altova\MapForce2017\MapForceExamples\Tutorial\PersonDB-dyn.mfd.
The source database file (available in the same folder as the mapping) includes a Person table
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Processing Multiple Input or Output Files Dynamically
165
which contains 21 records. The aim of the example is to generate a separate XML file for each
record in the Person table.
As the "PrimaryKey" field uniquely identifies each person in the table, this is the item we will use
to split up the source database into separate files. To achieve the goal of this example, do the
following:
1.
2.
3.
4.
Insert a concat function (you can drag it from the core | string functions library of the
Libraries pane).
Insert a constant (on the Insert menu, click Constant) and enter ".xml" as its value.
Click the File (
) or File/String (
) button of the target component and
select Use Dynamic File Names Supplied by Mapping.
Create the connections as shown below and then click the Output tab to see the result of
the mapping.
PersonDB-dyn.mfd (MapForce Professional Edition)
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
166
Designing Mappings
Processing Multiple Input or Output Files Dynamically
Note that the resulting output files are named dynamically as follows:
The PrimaryKey field supplies the first part of the file name (for example, "1").
The constant supplies the file extension (".xml"), thus "1.xml" is the file name of the
first file.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
5.5
Supplying Parameters to the Mapping
167
Supplying Parameters to the Mapping
You can pass simple values to a mapping by means of simple input components. On the mapping
area, simple input components play the role of a source component which has a simple data type
(for example, string, integer, and so on) instead of a structure of items and sequences.
Consequently, you can create a simple input component instead of (or in addition to) a file-based
source component.
You can use simple input components in any the following MapForce transformation languages:
BUILT-IN (when you preview the mapping transformation directly in MapForce, from the
Preview tab)
BUILT-IN (when you run a compiled MapForce Server execution file)
XSLT 1.0, XSLT 2.0
XQuery
C++
C#
Java
In case of mappings executed with MapForce Server or by means of generated code, simple input
components become command line parameters. In case of mappings generated as XSLT
transformations, simple input components correspond to stylesheet parameters in the generated
XSLT file.
You can create each simple input component (or parameter) as optional or mandatory (see Input
Component Settings). If necessary, you can also create default values for the mapping input
parameters (see Creating a Default Input Value). This enables you to safely run the mapping even
if you do not explicitly supply a parameter value at mapping execution time.
Input parameters added on the main mapping area should not be confused with input parameters
in user-defined functions (see User-defined functions). There are some similarities and differences
between the two, as follows.
Input parameters on the mapping
Input parameters of user-defined functions
Added from Function | Insert Input menu.
Added from Function | Insert Input menu.
Can have simple data types (string, integer,
and so on).
Can have simple as well as complex data
types.
Applicable to the entire mapping.
Applicable only in the context of the function
in which they were defined.
When you create a reversed mapping (using the menu command Tools | Create Reversed
Mapping), a simple input component becomes a simple output component.
For an example, see Example: Using File Names as Mapping Parameters.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
168
5.5.1
Designing Mappings
Supplying Parameters to the Mapping
Adding Simple Input Components
To add a simple input to the mapping:
1.
2.
3.
4.
Make sure that the mapping window displays the main mapping (not a user-defined
function).
On the Function menu, click Input.
Enter a name and select the data type required for this input. If the input should be
treated as a mandatory mapping parameter, select the Input is required check box. For
a complete list of settings, see Simple Input Component Settings.
Click OK.
Create Input dialog b ox
You can change later any of the settings defined here (see Simple Input Component Settings).
5.5.2
Simple Input Component Settings
You can define the settings applicable to a simple input component either when adding it to the
mapping area. You can also change the setting at a later time, from the Edit Input dialog box.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Supplying Parameters to the Mapping
169
Edit Input dialog b ox
To open the Edit Input dialog box, do one of the following:
Select the component, and, on the Component menu, click Properties.
Double-click the component.
Right-click the component, and then click Properties.
The available settings are as follows.
Name
Enter a descriptive name for the input parameter corresponding to this
component. At mapping execution time, the value entered in this text box
becomes the name of the parameter supplied to the mapping; therefore, no
spaces or special characters are allowed.
Datatype
By default, any input parameter is treated as string data type. If the
parameter should have a different data type, select the respective value from
the list. When the mapping is executed, MapForce casts the input
parameter to the data type selected here.
Input is required
When enabled, this setting makes the input parameter mandatory (that is,
the mapping cannot be executed unless you supply a parameter value).
Disable this check box if you want to specify a default value for the input
parameter (see Creating a Default Input Value).
Specify value
This setting is applicable only if you execute the mapping during design
time, by clicking the Preview tab. It allows you to enter directly in the
component the value to use as mapping input.
Value
This setting is applicable only if you execute the mapping during design
time, by clicking the Preview tab. To enter a value to be used by
MapForce as mapping input, select the Specify Value check box, and then
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
170
Designing Mappings
Supplying Parameters to the Mapping
type the required value.
5.5.3
Creating a Default Input Value
After you add an Input component to the mapping area, notice the default item to the left of the
component.
Simple input component
The default item enables you to connect an optional default value to this input component, as
follows:
1.
Add a constant component (on the Insert menu, click Constant), and then connect it to
the default item of the input component.
2.
Double click the input component and make sure that the Input is required check box is
disabled. When you create a default input value, this setting is not meaningful and
causes mapping validation warnings.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
3.
Note:
5.5.4
Supplying Parameters to the Mapping
171
Click OK.
If you click the Specify value check box and enter a value in the adjacent box, the
entered value takes precedence over the default value when you preview the mapping (that
is, at design-time execution). However, the same value has no effect in the generated
code.
Example: Using File Names as Mapping Parameters
This example walks you through the steps required to execute a mapping that takes input
parameters at runtime. The mapping design file used in this example is available at the following
path: <Documents>\Altova\MapForce2017\MapForceExamples
\FileNamesAsParameters.mfd.
The mapping uses two input components: InputFileName and OutputFileName. These supply
the input file name (and the output file name, respectively) of the source and target XML file. For
this reason, they are connected to the File: <dynamic> item.
FileNamesAsParameters.mfd (MapForce Basic Edition)
Both the InputFileName and OutputFileName components are simple input components in the
mapping, so you can supply them as input parameters when executing the mapping. The
following sections illustrate how to do this in the following transformation languages:
XSLT 2.0, using RaptorXML Server
Built-in (MapForce Server Execution File), using MapForce Server
Java
XSLT 2.0
If you generate code in XSLT 1.0 or XSLT 2.0, the input parameters are written to the
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
172
Designing Mappings
Supplying Parameters to the Mapping
DoTransform.bat batch file, for execution by RaptorXML Server (see Automation with RaptorXML
Server). To use a different input (or output) file, you can either pass the required parameters at
command line, when calling the DoTransform.bat file, or edit the latter to include the required
parameters.
To supply a custom input parameter in the DoTransform.bat file:
1.
2.
3.
Generate the XSLT 2.0 code (File | Generate Code In | XSLT 2.0) from the
FileNamesAsParameters.mfd sample.
Copy the Altova_Hierarchical.xml file from the <Documents>\Altova\MapForce2017
\MapForceExamples\ directory to the directory where you generated the XSLT 2.0 code
(in this example, c:\codegen\examples\xslt2\). This file will act as custom parameter.
Edit DoTransform.bat to include the custom input parameter either before or after %* (as
highlighted below). Note that the parameter value is enclosed with single quotes. The
available input parameters are listed in the rem (Remark) section.
@echo off
RaptorXML xslt --xslt-version=2 -input="MappingMapToAltova_Hierarchical.xslt" -param=InputFileName:'Altova_Hierarchical.xml' %*
"MappingMapToAltova_Hierarchical.xslt"
rem --param=InputFileName:
rem --param=OutputFileName:
IF ERRORLEVEL 1 EXIT/B %ERRORLEVEL%
When you run the DoTransform.bat file, RaptorXML Server completes the transformation using
Altova_Hierarchical.xml as input parameter.
MapForce Server Execution File
To supply custom input parameters to a MapForce Server execution file:
1.
2.
3.
Compile the FileNamesAsParameters.mfd to a MapForce Server execution file (see
Compiling Mappings to MapForce Server Execution Files). When prompted, save the .mfx
execution file to a directory on your computer (in this example, c:\codegen\examples
\mfx\ ).
Copy the Altova_Hierarchical.xml file from the <Documents>\Altova\MapForce2017
\MapForceExamples\ directory to the directory where you saved the .mfx file. This file
will act as the custom parameter supplied to the mapping execution file.
Run MapForce Server with the following command:
MapForceServer.exe run "C:\codegen\examples\mfx
\FileNamesAsParameters.mfx" -p=InputFileName:"C:\codegen\examples\mfx
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Supplying Parameters to the Mapping
173
\Altova_Hierarchical.xml" -p=OutputFileName:"C:\codegen\examples\mfx
\OutputFile.xml"
In the MapForce Server command above, -p=InputFileName and -p=OutputFileName are the
input parameters to the mapping. You can use any file name as the value of -OutputFileName.
However, the file name supplied in -InputFileName parameter must exist as a physical file;
otherwise, the mapping will fail.
Note:
If you see the message "MapForceServer.exe is not recognized as an internal or external
command, operable program, or batch file", change the current directory to the one where
the MapForce Server executable is installed. To avoid changing path every time when you
run a mapping, add to your operating system's PATH environment variable the path of the
directory where MapForce Server executable is installed (for example, C:\Program Files
(x86)\Altova\MapForceServer2017\bin) .
Java
To supply a custom input parameter to a Java .jar application:
1.
2.
3.
4.
Generate the Java code (File | Generate Code In | Java) from the
FileNamesAsParameters.mfd sample.
Compile the Java code into an executable JAR file (for instructions on how to do this in
Eclipse, see Example: Build a Java application with Eclipse and Ant).
Copy the Altova_Hierarchical.xml file from the <Documents>\Altova\MapForce2017
\MapForceExamples\ directory to the directory where the .jar file is. This file will act as
the custom parameter supplied to the Java mapping application.
At the command line, enter: java -jar Mapping.jar /InputFileName
"InputFile.xml"
If you use wildcards when passing parameters to .jar files, place the wildcard
parameters in quotes, for example:
java -jar Mapping.jar /InputFileName "altova-*.xml"
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
174
5.6
Designing Mappings
Returning String Values from a Mapping
Returning String Values from a Mapping
Use a simple output component when you need to return a string value from the mapping. On the
mapping area, simple output components play the role of a target component which has a string
data type instead of a structure of items and sequences. Consequently, you can create a simple
output component instead of (or in addition to) a file-based target component. For example, you
can use a simple output component to quickly test and preview the output of a function (see
Example: Testing Function Output). The main purpose of a simple output component is, however,
to get back a string when calling the MapForce Server API, without writing any files.
Simple output components should not be confused with output parameters of user-defined
functions (see User-defined functions). There are some similarities and differences between the
two, as follows.
Output components
Output parameters of user-defined
functions
Added from Function | Insert Output menu.
Added from Function | Insert Output menu.
Have "string" as data type.
Can have simple as well as complex data
types.
Applicable to the entire mapping.
Applicable only in the context of the function
in which they were defined.
If necessary, you can add multiple simple output components to a mapping. You can also use
simple output components in combination with file-based and database target components. When
your mapping contains multiple target components, you can preview the data returned by a
particular component by clicking the Preview (
) button in the component title bar, and then
clicking the Output tab on the Mapping window.
You can use simple output components as follows in MapForce transformation languages:
Language
How it works
BUILT-IN (when previewing
the mapping
transformation)
You can preview Output components in the same way as you
would preview a file-based mapping output—by clicking the
Output tab on the Mapping window.
BUILT-IN (when running the
MapForce Server execution
file)
When you run a compiled MapForce Server execution file (see
Compiling a MapForce mapping), the mapping output is returned
in the standard output stream (stdout), so you can view it or
redirect to a file. For example, assuming that the name of the
MapForce server execution file is MyMapping.mfx, use the
following syntax to redirect the mapping output to output.txt file
and any errors to the log.txt file:
MapForceServer.exe run MyMapping.mfx >output.txt
2>log.txt
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
XSLT 1.0, XSLT 2.0
Returning String Values from a Mapping
175
If the generated XSLT files, a simple output components defined
in the mapping becomes the output of the XSLT transformation.
If you are using RaptorXML Server, you can instruct RaptorXML
Server to write the mapping output to the file passed as value to
the --output parameter.
To write the output to a file, add or edit to the --output
parameter in the DoTransform.bat file. For example, the
following DoTransform.bat file has been edited to write the
mapping output to the Output.txt file (see highlighted text).
RaptorXML xslt --xslt-version=2 -input="MappingMapToResult1.xslt" -output="Output.txt" %* "MappingMapToResult1.xslt"
If an --output parameter is not defined, the mapping output will
be written to the standard output stream (stdout) when the
mapping is executed.
C++, C#, Java
In the generated C++, C#, and Java code, the mapping output is
written to the standard output of the generated application.
If the mapping contains multiple target components, the
generated application concatenates the standard output of each
target component and returns it as one unified standard output.
When you create a reversed mapping (using the menu command Tools | Create Reversed
Mapping), the simple output component becomes a simple input component.
5.6.1
Adding Simple Output Components
To add an Output component to the mapping area:
1.
2.
3.
4.
Make sure that the mapping window displays the main mapping (not a user-defined
function).
On the Function menu, click Output.
Enter a name for the component.
Click OK.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
176
Designing Mappings
Returning String Values from a Mapping
Create Output dialog b ox
You can change the component name at any time later, in one of the following ways:
Select the component, and, on the Component menu, click Properties.
Double-click the component header.
Right-click the component header, and then click Properties.
5.6.2
Example: Previewing Function Output
This example illustrates how to preview the output returned by MapForce functions with the help of
simple output components. You will make the most of this example if you already have a basic
understanding of functions in general, and of MapForce functions in particular. If you are new to
MapForce functions, you may want to refer to Using Functions before continuing.
Our aim is to add a number of functions to the mapping area, and learn how to preview their output
with the help of simple output components. In particular, the example uses a few simple functions
available in the core library. Here is a summary of their usage:
string-length
Returns the number of characters in the string provided as argument. For
example, if you pass to this function the value "Lorem ipsum", the result is
"11", since this is the number of characters that the text "Lorem ipsum"
takes.
substring-after
Returns the part of the string that occurs after the separator provided as
argument. For example, if you pass to this function the value "Lorem
ipsum" and the space character (" "), the result is "ipsum".
substringbefore
Returns the part of the string that occurs before the separator provided as
argument. For example, if you pass to this function the value "Lorem
ipsum" and the space character (" "), the result is "Lorem".
To test each of these functions against a custom text value ("Lorem ipsum", in this example),
follow the steps below:
1.
Add a constant with the value "Lorem ipsum" to the mapping area (use the menu
command Insert | Constant). The constant will be the input parameter for each of the
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
2.
3.
4.
5.
Returning String Values from a Mapping
177
functions to be tested.
Add the string-length, substring-after, and substring-before functions to the
mapping area, by dragging them to the mapping area from the core library, string
functions section.
Add a constant with an empty space (" ") as value. This will be the separator parameter
required by the substring-after and substring-before functions.
Add three simple output components (use the menu command Function | Insert
Output). In this example, they have been named Result1, Result2, and Result3, although
you can give them another title.
Connect the components as illustrated below.
Testing function output with simple output components
As shown in the sample above, the "Lorem ipsum" string acts as input parameter to each of the
string-length, substring-after, and substring-before functions. In addition to this, the
substring-after and substring-before functions take a space value as second input
parameter. The Result1, Result2, and Result3 components can be used to preview the result of
each function.
To preview the output of any function
Click the Preview (
) button in the component title bar, and then click the Output tab
on the Mapping window.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
178
5.7
Designing Mappings
Using Variables
Using Variables
Variables are a special type of component used to store an intermediate mapping result for further
processing. They might be necessary in situations where you want to temporarily "remember"
some data on the mapping and process it in some way (for example, filter it, or apply some
functions) before it is copied to the target component.
Variables can be of simple type (for example, string, integer, boolean, etc) or complex type (a tree
structure).
Simple variab le
You can create a variable of complex type by supplying an XML schema which expresses the
structure of the variable. If the schema defines any elements globally, you can choose which one
should become the root node of the variable structure. Note that a variable does not have any
associated instance XML file; the data of the variable is computed at mapping runtime.
Complex variab le created from an XML schema
It is also possible to create variables of complex type from databases. In case of databases, you
can choose a specific database table as root item for the variable structure.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Using Variables
179
Complex variab le created from a datab ase tab le
In the images above, you may notice that each variable has an item called compute-when.
Connecting this item is optional; this enables you to control how the variable value should be
computed on the mapping (see Changing the Context and Scope of Variables).
When necessary, items of a variable structure can be duplicated to accept data from more than
one source connection, similar to how this is done for standard components (see Duplicating
Input). This does not apply, however, to variables created from database tables.
Simple variab le with duplicated inputs
One of the most important things about variables is that they are sequences, and can be used to
create sequences. The term "sequence" here means a list of zero or more items (see also
Mapping Rules and Strategies). This makes it possible for a variable to process multiple items for
the duration of the mapping lifetime. If, however, you want to assign a value once to a variable and
keep it the same for the rest of the mapping, it is also possible (see Changing the Context and
Scope of Variables).
To some extent, variables can be compared to intermediate components of a chained mapping
(see Chained Mappings). However, they are more flexible and convenient if you don't need to
produce intermediary files at each stage in the mapping. The following table outlines differences
between variables and chained mappings.
Chained mappings
Variables
Chained mappings involve two totally
independent steps. For example, let's assume
a mapping that has three components A, B,
and C. Running the mapping involves two
stages: executing the mapping from A to B,
and then executing the mapping from B to C.
While the mapping is executed, variables are
evaluated according to their context and
scope. Their context and scope can be
influenced (see Changing the Context and
Scope of Variables).
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
180
Designing Mappings
Chained mappings
Variables
When the mapping is executed, intermediate
results are stored externally in files.
When the mapping is executed, intermediate
results are stored internally. No external files
containing a variable's results are produced.
The intermediate result can be previewed
using the preview
button.
A variable's result cannot be previewed, since
it is computed at mapping runtime.
Note:
5.7.1
Using Variables
Variables are not supported if the mapping transformation language is set to XSLT 1.0.
Adding Variables
There are several ways to add variables to a mapping, as shown below.
Using a menu or toolbar command
1.
On the Insert menu, click Variable. (Alternatively, click the Variable
button).
2.
Select the type of variable you want to insert (simple or complex type).
toolbar
If you select "Complex type", there are a few additional steps:
3.
Click Choose to select the source which should provide the structure of the variable (for
example, an XML Schema or database).
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
4.
Using Variables
181
When prompted, specify a root item of the structure. In case of XML Schemas, the root
item can be any element defined globally. In case of databases, the root item can be any
table.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
182
Designing Mappings
Using Variables
Using a context menu
Right-click the output connector of a component (in this example, "Article") and select
Create Variable from Source node.
This creates a complex variable using the same source schema and automatically
connects all items with a Copy-All connection.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Using Variables
183
Right-click the input connector of a target component and select Create Variable for
Target Node. This creates a complex variable using the same schema as the target, and
automatically connects all items with a Copy-All connection.
Right-click the output connector of a filter component (on-true/on-false) and select Create
Variable from Source Node. This creates a complex component using the source
schema, and automatically uses the item linked to the filter input as the root element of
the intermediate component.
5.7.2
Changing the Context and Scope of Variables
Every variable has a compute-when input item which 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 the mapping performance.
The "compute-when" item
In the following text, a subtree means the set of an item/node in a target component and all of its
descendants, for example, a <Person> element with its <FirstName> and <LastName> child
elements.
A 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 contain one or even zero elements. This depends
on what is connected to the input side of the variable, and to any parent items in the source and
target components.
"Compute-when" is not connected (default)
If the compute-when input item is not connected (to an output node of a source component), the
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
184
Designing Mappings
Using Variables
variable value is computed whenever it is first used in a target subtree (either directly via a
connector from the variable component 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.
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" is connected
By connecting an output connector of a source component to compute-when, the variable is
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. That is, 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" (see Mapping Rules and Strategies).
"Compute-once"
If necessary, you can choose to compute the variable value once before each of the target
components, making the variable essentially a global constant for the rest of the mapping. To do
this, right-click the compute-when item and select Compute Once from the context menu:
When you change the scope of a variable to compute-when=once, the input connector is removed
from the compute-when item, since such a variable is only evaluated once.
In a user-defined function, the compute-when=once variable is evaluated each time the function is
called, before the actual function result is evaluated.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Using Variables
185
Parent-context
Adding a parent-context may be necessary, for example, if your mapping uses multiple filters and
you need an additional parent node to iterate over, see also Overriding the Mapping Context.
To add a parent-context to a variable, right-click the root node (in this example, "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 in a different source component.
5.7.3
Example: Counting Database Table Rows
The mapping illustrated in this example is available as DB_UserList.mfd in the <Documents>
\Altova\MapForce2017\MapForceExamples\ folder. This mapping extracts user records from a
database table called "Users" and writes them to an XML file. The database column "Username"
contains both the first name and the surname of a person (for example, "Vernon Callaby"). This
mapping has the following goals:
1.
2.
3.
For each record in the "Users" table, create a new Person element in the XML file.
Split the value extracted from the database field "Username" into two separate fields in
the XML file ("First" and "Last").
For each record, find its sequential number compared to the number of total records
present in the database (for example, "Record 1 of 4") and write this information to the
Details element.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
186
Designing Mappings
Using Variables
DB_UserList.mfd
As illustrated above, in order to achieve the first goal, a connection is drawn between the source
"Users" table and the Person element of the target XML file. This ensures that, for each record in
the source table, a new Person element will be created in the target.
The value of the field "Username" is supplied to the substring-before and substring-after
functions. These two functions extract the text before and after the space character (" "),
respectively, which takes care of the second mapping goal.
Finally, to achieve the third goal, the mapping uses the count function. The result of the count
function is passed on to a variable. The variable ensures that this result is stored on the mapping
and available when writing the "Details" element of each person to the target XML. Note that, for
efficiency reasons, database records should be counted only once, so the variable scope is set
to compute-when=once (see Changing the Context and Scope of Variables)
5.7.4
Example: Filtering and Numbering Nodes
The mapping illustrated in this example is available as PositionInFilteredSequence.mfd in the
<Documents>\Altova\MapForce2017\MapForceExamples\ folder.
This mapping reads an XML file which contains contact data of several people, filters them, and
writes them to a target XML file. The goal of the mapping is to filter from the source XML file only
those people whose last name begins with letter "M" or a subsequent letter. Secondly, the
extracted contacts must be numbered. The number is going to act as the unique identifier of each
contact in the target XML file.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Using Variables
187
PositionInFilteredSequence.mfd
To achieve the goal above, the following component types were added to the mapping:
A filter (see Filters and Conditions )
A complex variable (see Adding Variables)
The functions greater and position (see Working with Functions)
A constant (To add a constant, select the menu command Insert | Constant).
The variable uses the same schema as the source component. If your right-click the variable and
select Properties from the context menu, notice that the node BranchOffices/Office/Contact is
selected as root node for this variable structure.
First, data of the source component is passed on to the filter. The filter passes onwards to the
variable only those records that meet the filter condition. Namely, the filter is configured to get
only those Contact nodes where the first name is equal or greater than M". To achieve this, the
function greater compares each last item with the constant value "M".
The variable has the compute-when input connected to the root item of the source component
(BranchOffices). At runtime, this causes the variable to be re-evaluated whenever a new item is
read from the sequence in the source component. In this mapping, however, connecting or not
connecting the compute-when item does not make a difference. The reason is that the variable is
connected to the Contact source item (indirectly through the filter), and it would compute as
many times as there are instances of Contact which meet the filter condition.
The position functions returns, for each iteration of the variable, the number of the current
sequence. Only eight contacts meet the filter condition; therefore, if you preview the mapping and
look at the output, notice how IDs 1 through 8 were written to the ID element of the target
component.
In case you were wondering why the variable was necessary at all, it is because of the
requirement to number all records. Had we connected the filter result directly to the target
component, there would have been no way to number each occurrence of Contact. The purpose
of the variable in this mapping is, therefore, to store each instance of Contact temporarily on the
mapping, so that it can be numbered before it is written to the target.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
188
5.7.5
Designing Mappings
Using Variables
Example: Grouping and Subgrouping Records
The mapping illustrated in this example is available as
DividePersonsByDepartmentIntoGroups.mfd in the <Documents>\Altova\MapForce2017
\MapForceExamples\ folder.
This mapping processes an XML file that contains employee records of a fictitious company. The
company has two offices: "Nanonull, Inc." and "Nanonull Partners, Inc". Each office has several
departments (for example, "IT", "Marketing", and so on), and each department has one or more
employees. The goal of the mapping is to create groups of maximum three people from each
department, regardless of the office. The size of each group is three by default; however, it should
be easy to change if necessary. Each group must be saved as a separate XML file, with the name
having the format "<Department Name>_GroupN" (for example, Marketing_Group1.xml,
Marketing_Group2.xml, and so on).
DividePersonsByDepartmentIntoGroups.mfd
As illustrated above, in order to achieve the mapping goal, a complex variable was added to the
mapping, and a few other component types (primarily functions). The variable has the same
structure as a Department item in the source XML. If you right-click the variable in order to view
its properties, you will notice that it uses the same XML schema as the source component, and
has Department as root element. Importantly, the variable has two nested parent-context
items, which ensure that the variable is computed first in the context of each department, and
then in the context of each group within each department (see also Changing the Context and
Scope of Variables).
Initially, the mapping iterates through all departments in order to obtain the name of each
department (this will be subsequently required to create the file name corresponding to each
group). This is achieved by connecting the group-by function to the Department source item, and
by supplying the department name as grouping key.
Next, within the context of each department, a second grouping takes place. Namely, the
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Using Variables
189
mapping calls the group-into-blocks function in order to create the required groups of people.
The size of each group is supplied by a simple input component which has a default value of "3".
The default value is supplied by a constant. In this example, in order to change the size of each
group, one can easily modify the constant value as required. However, the "size" input component
can also be modified so that, if the mapping is run by generated code or with MapForce Server,
the size of each group could be conveniently supplied as a parameter to the mapping. For more
information, see Supplying Parameters to the Mapping.
Next, the value of the variable is supplied to the target PersonList XML component. The file name
for each created group was computed by concatenating the following parts, with the help of the
concat function:
1.
2.
3.
4.
The name of each department
The string "_Group"
The number of the group in the current sequence (for example, "1" if this is the first group
for this department)
The string ".xml"
The result of this concatenation is stored in the Name item of the variable, and then supplied as a
dynamic file name to the target component. This causes a new file name to be created for each
received value. In this example, the variable computes eight groups in total, so eight output files
are created when the mapping runs, as required. For more information about this technique, see
Processing Multiple Input or Output Files Dynamically.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
190
5.8
Designing Mappings
Sorting Data
Sorting Data
To sort input data based on a specific sort key, use a Sort component. The Sort component
supports the following target languages: XSLT2, XQuery, and Built-in. When the transformation
language is "Built-in", the Sort component can be used to sort database table data. Better
performance is, however, achieved using an SQL-WHERE/ORDER component. For more details,
see Filtering and Sorting Database Data (SQL WHERE/ORDER).
To add a sort component to the mapping, do one of the following:
Right-click an existing connection, and select Insert Sort: Nodes/Rows from the context
menu. This inserts the Sort component and automatically connects it to the source and
target components. For example, in the mapping below, the Sort component was inserted
between a variable and an XML component. The only thing that remains to be connected
manually is the sorting key (the field by which you want to sort).
On the Insert menu, click Sort (alternatively, click the Sort
inserts the Sort component in its "unconnected" form.
toolbar button). This
As soon as a connection is made to the source component, the title bar name changes
to that of the item connected to the nodes/rows item.
To define the item by which you want to sort:
Connect the item by which you want to sort to the key parameter of the Sort component.
For example, in the mapping below, the Person nodes/rows are sorted by the field Last.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Sorting Data
191
To change the sort order:
Click the
icon in the Sort component. It changes to
order has been reversed.
to show that the sort
To sort input data consisting of simple type items:
Connect the item to both the nodes/rows and key parameters of the sort component. In
the mapping below, the element of simple type first is being sorted.
To sort strings using language-specific rules:
Double-click the header of the Sort component to open the Sort Properties dialog box.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
192
Designing Mappings
Sorting Data
Unicode codepoint collation: This (default) option compares/orders strings based on code point
values. Code point values are integers that have been assigned to abstract characters in the
Universal Character Set adopted by the Unicode Consortium. This option allows sorting across
many languages and scripts.
Language-specific collation: This option allows you to define the specific language and country
variant you want to sort by. This option is supported when using the BUILT-IN execution engine.
For XSLT, support depends on the specific engine used to execute the code.
5.8.1
Sorting by Multiple Keys
After you add a Sort component to the mapping, one sorting key called key is created by default.
Default Sort component
If you want to sort by multiple keys, adjust the Sort component as follows:
Click the Add Key ( ) icon to add a new key (for example, key2 in the mapping below).
Click the Delete Key ( ) icon to delete a key.
Drop a connection onto the icon to add a key and also connect to it.
A mapping which illustrates sorting by multiple key is available at the following path:
<Documents>\Altova\MapForce2017\MapForceExamples\SortByMultipleKeys.mfd.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Sorting Data
193
SortByMultipleKeys.mfd
In the mapping above, Person records are sorted by three sorting keys:
1.
2.
3.
Shares (number of shares a person holds)
Last (last name)
First (first name)
Note that the position of the sorting key in the Sort component determines its sort priority. For
example, in the mapping above, records are initially sorted by the number of shares. This is the
sorting key with the highest priority. If the number of shares is the same, people are then sorted
by their last name. Finally, when multiple people have the same number of shares and the same
last name, the person's first name is taken into account.
The sort order of each key can be different. In the mapping above, the key Shares has a
descending sort order (Z-A), while the other two keys have ascending sort order (A-Z).
5.8.2
Sorting with Variables
In some cases, it may be necessary to add intermediate variables to the mapping in order to
achieve the desired result. This example illustrates how to extract records from an XML file, and
sort them, with the help of intermediate variables. The example is accompanied by a mapping
sample located at the following path: <Documents>\Altova\MapForce2017
\MapForceExamples\Altova_Hierarchical_Sort.mfd.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
194
Designing Mappings
Sorting Data
Altova_Hierarchical_Sort.mfd
This mapping reads data from a source XML file called Altova_Hierarchical.xml and writes it to
a target XML file. As shown above, the source XML contains information about a fictitious
company. The company is divided into offices. Offices are sub-divided into departments, and
departments are further divided into people.
The target XML component, PersonList, contains a list of Person records. The Details item is
meant to store information about the office and department where the person belongs.
The aim is to extract all persons from the source XML and sort them alphabetically by last name.
Also, the office and department name where each person belongs must be written to the Details
item.
To achieve this goal, this example makes use of the following component types:
1.
2.
The concat function. In this mapping, this function returns a string in the format
Office(Department). It takes as input the office name, the department name, and two
constants which supply the start and end brackets. See also Working with Functions.
An intermediate variable. The role of the variable is to bring all data relevant to a person
into the same mapping context. The variable causes the mapping to look up the
department and office of each person, in the context of each person. To put it differently,
the variable "remembers" the office and department name to which a person belongs.
Without the variable, the context would be incorrect, and the mapping would produce
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
3.
Sorting Data
195
unwanted output (for more information about how a mapping is executed, see Mapping
Rules and Strategies). Notice that the variable replicates the structure of the target XML
file (it uses the same XML schema). This makes it possible to connect the sort result to
the target, through a Copy-All connection. See also Using Variables and Copy-All
Connections.
A Sort component, which performs the actual sorting. Notice that the key input of the
Sort component is connected to the Last item of the variable, which sorts all person
records by their last name.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
196
5.9
Designing Mappings
Filters and Conditions
Filters and Conditions
When you need to filter data, or get a value conditionally, you can use one of the following
component types:
Filter: Nodes/Rows (
)
SQL WHERE/ORDER (
If-Else Condition (
)
)
You can add these components to the mapping either from the Insert menu, or from the Insert
Component toolbar. Importantly, each of the components above has specific behavior and
requirements. The differences are explained in the following sections.
Filtering nodes or rows
When you need to filter data, including XML nodes or CSV rows, use a Filter Nodes/Rows
component. The Filter Nodes/Rows component enables you to retrieve a subset of nodes from a
larger set of data, based on a true or false condition. Its structure on the mapping area reflects
this:
In the structure above, the condition connected to bool determines whether the connected node/
row goes to the on-true or on-false output. Namely, if the condition is true, the node/row will be
redirected the on-true output. Conversely, if the condition is false, the node/row will be
redirected to the on-false output.
When your mapping needs to consume only items that meet the filter condition, you can leave
the on-false output unconnected. If you need to process the items that do not meet the filter
condition, connect the on-false output to a target where such items should be redirected. If you
want to add an exception when the filter condition is not met, connecting the on-false output is
mandatory (see Adding Exceptions).
For a step-by-step mapping example, see Example: Filtering Nodes.
Filtering database data
Filter Nodes/Rows components can filter data from any other component structure supported by
MapForce, including databases. However, if you want to filter data from a database, it is
recommended to use a SQL WHERE/ORDER component instead. The SQL WHERE/ORDER
component is optimized for working with databases and provides better performance than a Filter
Nodes/Rows component.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Filters and Conditions
197
For more information about such components, see SQL WHERE / ORDER Component.
Returning a value conditionally
If you need to get a single value (not a node or row) conditionally, use an If-Else Condition. Note
that If-Else conditions are not suitable for filtering nodes or rows. Unlike Filter Nodes/Rows
components, an If-Else Condition returns a value of simple type (such as a string or integer).
Therefore, If-Else Conditions are only suitable for scenarios where you need to process a simple
value conditionally. For example, let's assume you have a list of average temperatures per month,
in the format:
<Temperatures>
<data temp="19.2" month="2010-06" />
<data temp="22.3" month="2010-07" />
<data temp="19.5" month="2010-08" />
<data temp="14.2" month="2010-09" />
<data temp="7.8" month="2010-10" />
<data temp="6.9" month="2010-11" />
<data temp="-1.0" month="2010-12" />
</Temperatures>
An If-Else Condition would enable you to return, for each item in the list, the value "high" if
temperature exceeds 20 degrees Celsius, and value "low" if temperature is lower than 5 degrees
Celsius.
On the mapping, the structure of the If-Else Condition looks as follows:
If the condition connected to bool is true, then the value connected to value-true is output as
result. If the condition is false, the value connected to value-false is output as result. The data
type of result is not known in advance; it depends on the data type of the value connected to
value-true or value-false. The important thing is that it should always be a simple type (string,
integer, and so on). Connecting input values of complex type (such as nodes or rows) is not
supported by If-Else Conditions.
If-Else Conditions are extendable. This means that you can add multiple conditions to the
component, by clicking the Add ( ) button. To delete a previously added condition, click the
Delete ( ) the button. This feature enables you to check for multiple conditions and return a
different value for each condition, if it is true.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
198
Designing Mappings
Filters and Conditions
Expanded If-Else Conditions are evaluated from top to bottom (first conditions is checked first,
then the second one, and so on). If you want to return a value when none of the conditions are
true, connect it to otherwise.
For a step-by-step mapping example, see Example: Returning a Value Conditionally.
5.9.1
Example: Filtering Nodes
This example shows you how to filter nodes based on a true/false condition. A Filter: Nodes/
Rows (
) component is used to achieve this goal. The technique illustrated in this example
works in the same way not only for XML, but also for other component types, such as CSV or
text. In case of databases, although you can use a filter, it is recommended to use a SQL
WHERE/ORDER component instead, for better performance (see SQL WHERE / ORDER
Component).
The mapping described in this example is available at the following path: <Documents>\Altova
\MapForce2017\MapForceExamples\MarketingExpenses.mfd.
As shown above, the mapping reads data from a source XML which contains an expense report
("ExpReport") and writes data to a target XML ("MarketingExpenses"). There are several other
components between the target and source. The most relevant component is the expense-item
filter (
), which represents the subject of this topic.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Filters and Conditions
199
The goal of the mapping is to filter out only those expense items that belong to the Marketing
department. To achieve this goal, a filter component has been added to the mapping. (To add a
filter, click the Insert menu, and then click Filter: Nodes/Rows.)
To identify whether each expense item belongs to Marketing, this mapping looks at the value of
the "expto" attribute in the source. This attribute has the value "Marketing" whenever the expense
is a marketing expense. For example, in the code listing below, the first and third expense item
belongs to Marketing, the second belongs to Development, and the fourth belongs to Sales:
...
<expense-item type="Meal" expto="Marketing">
<Date>2003-01-01</Date>
<expense>122.11</expense>
</expense-item>
<expense-item type="Lodging" expto="Development">
<Date>2003-01-02</Date>
<expense>122.12</expense>
</expense-item>
<expense-item type="Lodging" expto="Marketing">
<Date>2003-01-02</Date>
<expense>299.45</expense>
</expense-item>
<expense-item type="Entertainment" expto="Sales">
<Date>2003-01-02</Date>
<expense>13.22</expense>
</expense-item>
...
XML input b efore the mapping is executed
On the mapping area, the node/row input of the filter is connected to the expense-item node in
the source component. This ensures that the filter component gets the list of nodes that it must
process.
To add the condition based on which filtering should occur, we have added the equal function
from the MapForce core library (for more information, see Working with Functions). The equal
function compares the value of the "type" attribute to a constant which has the value "Marketing".
(To add a constant, click the Insert menu, and then click Constant.)
Since we need to filter only those items that satisfy the condition, we connected only the on-true
output of the filter to the target component.
When you preview the mapping result, by clicking the Output tab, MapForce evaluates, for each
expense-item node, the condition connected to the bool input of the filter. When the condition is
true, the expense-item node is passed on to the target; otherwise, it is ignored. Consequently,
only the expense items matching the criteria are displayed in the output:
...
<expense-item>
<type>Meal</type>
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
200
Designing Mappings
Filters and Conditions
<Date>2003-01-01</Date>
<expense>122.11</expense>
</expense-item>
<expense-item>
<type>Lodging</type>
<Date>2003-01-02</Date>
<expense>299.45</expense>
</expense-item>
...
XML output after the mapping is executed
5.9.2
Example: Returning a Value Conditionally
This example shows you how to return a simple value from a component, based on a true/false
condition. An If-Else Condition (
) is used to achieve the goal. Note that If-Else Conditions
should not be confused with filter components. If-Else Conditions are only suitable when you
need to process simple values conditionally (string, integer, etc.). If you need to filter complex
values such as nodes, use a filter instead (see Example: Filtering Nodes).
The mapping described in this example is available at the following path: <Documents>\Altova
\MapForce2017\MapForceExamples\ClassifyTemperatures.mfd.
This mapping reads data from a source XML which contains temperature data ("Temperatures")
and writes data to a target XML which conforms to the same schema. There are several other
components between the target and source, one of them being the if-else condition (highlighted in
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Filters and Conditions
201
red), which is also the subject of this topic.
The goal of the mapping is to add short description to each temperature record in the target.
Specifically, if temperature is above 20 degrees Celsius, the description should be "high". If the
temperature is below 5 degrees Celsius, the description should be "low". For all other cases, no
description should be written.
To achieve this goal, conditional processing is required; therefore, an If-Else Condition has been
added to the mapping. (To add an If-Else Condition, click the Insert menu, and then click If-Else
Condition.) In this mapping, the If-Else Condition has been extended (with the help of the
button) to accept two conditions: bool1 and bool2.
The conditions themselves are supplied by the greater and less functions, which have been
added from the MapForce core library (for more information, see Working with Functions). These
functions evaluate the values provided by two input components, called "upper" and "lower". (To
add an input component, click the Insert menu, and then click Insert Input. For more information
about input components, see Supplying Parameters to the Mapping.)
The greater and less functions return either true or false. The function result determines what is
written to the target instance. Namely, if the value of the "temp" attribute in the source is greater
than 20, the constant value "high" is passed to the if-else condition. If the value of the "temp"
attribute in the source is less than 5, the constant value "low" is passed on to the if-else
condition. The otherwise input is not connected. Therefore, if none of the above conditions is
met, nothing is passed to the result output connector.
Finally, the result output connector supplies this value (once for each temperature record) to the
"desc" attribute in the target.
When you are ready to preview the mapping result, click the Output tab. Notice that the resulting
XML output now includes the "desc" attribute, whenever the temperature is either greater than 20
or lower than 5.
...
<data
<data
<data
<data
<data
<data
<data
<data
...
temp="-3.6" month="2006-01" desc="low"/>
temp="-0.7" month="2006-02" desc="low"/>
temp="7.5" month="2006-03"/>
temp="12.4" month="2006-04"/>
temp="16.2" month="2006-05"/>
temp="19" month="2006-06"/>
temp="22.7" month="2006-07" desc="high"/>
temp="23.2" month="2006-08" desc="high"/>
XML output after the mapping is executed
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
202
Designing Mappings
Joining Data
5.10 Joining Data
Sometimes, you may need to combine data from two or more structures based on some condition
(for example, if field A in the first structure has the same value as field B in the second structure).
For such mapping requirements, a Join component can be used.
A Join component is a MapForce component which enables joining two or more structures on the
mapping based on custom-defined conditions. It returns the association (joined set) of items that
satisfy the condition. Joins are particularly useful to combine data from two structures which
share a common field (such as an identity).
For example, on the mapping illustrated below, the middle component is a "Join" component. In
this mapping, two XML structures (a list of people and a list of addresses) are being joined. The
goal here is to get the full details of each person into a target XML file. The FirstName and
LastName fields act as joining keys. Namely, if value of FirstName and LastName (under Person)
is the same as that of FirstName and LastName (under Address), the address details belong to
one and the same person and they become "joined". Any items from the joined structure can
further be mapped to a subsequent target (in this case, an XML file). The join condition itself is
defined in the properties of the Join component, by clicking the Define Join Condition (
)
button. This example is accompanied by a mapping sample and is explained in more detail in
Example: Join XML Structures.
JoinPeopleInfo.mfd
As illustrated above, the source structures and the Join component are connected by means of
"Copy-All" connection, which reduces the mapping clutter. In general, such connections are
created automatically by MapForce when the context is relevant (for more information, see CopyAll Connections).
The structures that are to be joined may either be from separate components (as in the mapping
above), or belong to the same component. The structures to be joined may also be of different
kinds (for example, an XML structure and a database table). For more information about database-
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Joining Data
203
related joins, see Joining Database Data.
To add a Join component:
1.
Set the mapping transformation language to BUILT-IN (to do this, either click the
toolbar button, or use the Output | Built-In Execution Engine menu command).
2.
On the Insert menu, click Join. Alternatively, click the Join (
) toolbar button. The
Join component appears on the mapping. By default, it accepts data from two structures,
so it has two nodes/rows inputs. If necessary, you can add new inputs to the join by
clicking the Add Input ( ) button, see Joining Three or More Structures.
3.
Connect the structures that are to be joined to the nodes/rows items of the join
component.
Add the condition for the join (or multiple conditions). To do this, right-click the Join
component and select Properties. Join conditions can also be added directly from the
mapping, by connecting the Boolean result of some function to the condition item of the
Join component. In certain cases when database tables are joined, the join condition (or
conditions) can be created automatically by MapForce. For further information, see
Adding Join Conditions.
4.
Notes:
Join components are supported when the target language of the mapping is set to BUILTIN. Code generation in C#, C++, or Java is not supported.
When a structure is not a valid or supported input source for the join, MapForce displays
hints either immediately directly on the mapping, or in the Messages window, when you
validate the mapping (see Validating Mappings).
Join components should not be connected to input parameters or results of inline userdefined functions. If such connections exist, validation errors will occur during mapping
validation.
When you connect eligible database components (such as tables or views) directly to a
Join component, an SQL mode (
) button automatically appears at the top-right
corner of the Join component. When enabled, this button provides special SQL features
applicable to the join operation (see About Joins in SQL Mode).
It is not possible to connect the output of the joined item to another Join component. If
necessary, however, you can connect a partial result of one join to another one.
Join components compared to other component types
In some cases, complex variables or filters can be used instead of Join components to achieve
the same results (see Using Variables and Filters and Conditions, respectively). However, unlike
other component types, Join components make the mapping easier to understand, because you
can see at a glance the data that is being joined. Additionally, if SQL mode is enabled on the join
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
204
Designing Mappings
Joining Data
component, the mapping performance improves significantly (this applies to database joins, see
Joining Database Tables).
Adding a parent context
In some special cases, in order to achieve a specific mapping result, you can explicitly provide a
mapping context (a so-called "parent context") for data connected to the Join component. To add
a parent context, right-click the joined item of the Join component, and select Add Parent
Context from the context menu. The Join component changes appearance to include an
additional parent-context input where you can connect the required source item. For more
information, see Overriding the Mapping Context.
5.10.1
Adding Join Conditions
A join works by combining items of two or more structures according to a condition, so a join
always requires at least one condition. There are several ways to add join conditions, as shown
below.
Note:
When database tables are joined in SQL mode, MapForce will create the join condition
(or conditions) automatically, based on foreign key relationships detected between tables.
For automatic join conditions to happen, the database tables must be in a child-parent
relationship on the MapForce component (that is, one table must be "parent" or "child" of
another one on the component), see Example: Join Tables in SQL Mode.
Approach 1: Add a join condition from the component properties
1.
2.
3.
On the mapping, make sure that at least two structures (or database tables) are
connected to the Join component. The Join component illustrated in this example is part
of the JoinPeopleInfo.mfd mapping available in the folder <Documents>\Altova
\MapForce2017\MapForceExamples\Tutorial\. This mapping is discussed in more
detail in Example: Join XML Structures.
On the Join component, click the Define Join Condition (
) button (or right-click the
header of the component, and select Properties from the context menu).
Select an item from the left structure and another one from the right structure (that is,
whenever the comparison of this pair returns true, the left and right structures become
joined).
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Joining Data
205
If you need to add multiple conditions, click Add Condition, and then select a new pair of
items. For example, in the image above, two join conditions are defined:
1.
2.
FirstName in the Structure 1 must be equal to FirstName in Structure 2, and
LastName in Structure 1 must be equal to LastName in Structure 2.
To remove a join condition, click the Delete
button next to it.
Notes:
When multiple join conditions exist, all of them must be satisfied in order for the two
structures to be joined. In other words, multiple conditions are joined by a logical AND
operation. This also includes optional conditions that were added from the mapping (see
Approach 2 below).
If more than two structures are connected to the Join component, such additional
structures appear in the drop-down list below "Structure 2". When you select such an
additional structure from the drop-down list, the left pane displays all structures that
occur before it on the Join component. This way you can define join conditions between
any of the multiple structures. For an example, see Example: Create CSV Report from
Multiple Tables.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
206
Designing Mappings
Joining Data
To view the data type of items in each structure, select the Show types check box. The
Show annotations option displays additional information about items, provided that such
information exists in the underlying schema (or database). If both check boxes are
selected, the layout changes to accommodate the display of both annotations and types,
for example:
Approach 2: Add a join condition from the mapping
On the mapping, add components which produce a Boolean value, and then connect the
Boolean output to the input of the condition item. For example, the equal function may
compare a value with some mapping item, and supply the Boolean result as input to the
condition item of the join component.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Note:
Joining Data
207
If no condition is defined from the join component properties (Approach 1), the condition
item of the join component must be connected (Approach 2).
Approach 3: Mixed approach
In the same mapping, it is possible to define some join conditions in component properties
(Approach 1) and combine them with the one from the mapping (Approach 2). However, if you
intend to join database tables in SQL mode, the conditions must be defined strictly using
Approach 1 (see also About Joins in SQL Mode).
5.10.2
Joining Three or More Structures
When you add a Join component to the mapping using the menu command Insert | Join, it
accepts two structures by default (that is, the component contains only two nodes/rows inputs).
If you need to join more than two structures, click the Add input ( ) button and create as many
nodes/rows as necessary. If you need to remove a nodes/rows input, click the Delete input (
) button. Note that a join requires at least two structures, so the button is only available when
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
208
Designing Mappings
Joining Data
more than two inputs exist.
When a join has multiple inputs, the join conditions must accordingly take into consideration each
of the inputs that you want to be joined, see Adding Join Conditions. For a step-by-step example
of how to join multiple database tables, see Example: Create CSV Report from Multiple Tables.
5.10.3
Example: Join XML Structures
This example shows you how to combine data from two XML structures conditionally, by using a
join component. The example is accompanied by a mapping sample which is available at the
following path: <Documents>\Altova\MapForce2017\MapForceExamples\Tutorial
\JoinPeopleInfo.mfd.
The purpose of this mapping is to collect people data (name, surname, address, email, and
phone) from two source XML files into a single target XML file.
The first XML file stores the name and surname of each person, as well as their email and phone,
as shown in the sample code listing below (note that the XML declaration, namespaces, and
some records have been omitted, for simplicity):
<People>
<Person>
<FirstName>Marquita</FirstName>
<LastName>Bailey</LastName>
<Email>m.bailey@nanonull.com</Email>
<Phone>555323698</Phone>
</Person>
<Person>
<FirstName>Totie</FirstName>
<LastName>Rea</LastName>
<Email>t.rea@nanonull.com</Email>
<Phone>555598653</Phone>
</Person>
</People>
People.xml
The second XML file stores the name and surname of each person, as well as their address
details:
<Addresses>
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Joining Data
209
<Address>
<FirstName>Marquita</FirstName>
<LastName>Bailey</LastName>
<City>Bridgedell</City>
<Street>Olive Street</Street>
<Number>4</Number>
</Address>
<Address>
<FirstName>Totie</FirstName>
<LastName>Rea</LastName>
<City>Roseford</City>
<Street>Evergreen Lane</Street>
<Number>34</Number>
</Address>
</Addresses>
Addresses.xml
The goal of the mapping is to combine the <Person> information from the first file with <Address>
information from the second file, wherever the first and last names match. Specifically, for each
<Person> in the first file, and for each <Address> in the second file, the FirstName and LastName
must be compared. If both values are the same, then the corresponding <Person> and <Address>
records refer to the same person, and must be joined. The target XML structure should look like
this:
<PeopleInfo>
<Row>
<FirstName>Marquita</FirstName>
<LastName>Bailey</LastName>
<City>Bridgedell</City>
<Street>Olive Street</Street>
<Number>4</Number>
<Email>m.bailey@nanonull.com</Email>
<Phone>555323698</Phone>
</Row>
<Row>
<FirstName>Totie</FirstName>
<LastName>Rea</LastName>
<City>Roseford</City>
<Street>Evergreen Lane</Street>
<Number>34</Number>
<Email>t.rea@nanonull.com</Email>
<Phone>555598653</Phone>
</Row>
</PeopleInfo>
PeopleInfo.xml
This mapping goal can be easily achieved by adding a Join component to the mapping. Note that
it is also possible to achieve the same result using other component types; however, in the steps
below, you will be using a Join component, which is the subject of this example.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
210
Designing Mappings
Joining Data
To create the required mapping, follow the steps below.
Step 1: Add the source XML files to the mapping
1.
2.
On the Insert menu, click XML Schema/File, and browse for the following source file:
<Documents>\Altova\MapForce2017\MapForceExamples\Tutorial\People.xml.
Repeat the step above for Addresses.xml (the second source file).
Step 2: Add the target schema file to the mapping
On the Insert menu, click XML Schema/File, and browse for <Documents>\Altova
\MapForce2017\MapForceExamples\Tutorial\PeopleInfo.xsd (the target XSD
schema file). When prompted to supply a sample XML file, click Skip. When prompted to
select a root element, select PeopleInfo as root element.
Step 3: Add the Join component
1.
On the Insert menu, click Join. (Alternatively, click the Join
toolbar button). At this
stage, the mapping should look as follows (you will need to drag and resize the
components in order to make them look as illustrated below):
Observe the structure of the Join component. It has two nodes/rows items, which makes
it possible to connect to it the two structures that need to be compared (in this case, the
Person and the Address structures).
2.
Draw a connection from Person to the first nodes/rows item of the Join component.
Likewise, connect Address to the second nodes/rows item.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
3.
4.
5.
Joining Data
211
As mentioned earlier, the join should take place only if the FirstName and LastName
values are equal in both structures. To define this condition, click the Define Join
Condition
button.
Select the pair of items that define the first join condition (FirstName under Structure 1,
and FirstName under Structure 2).
Click Add Condition, and repeat the step above for LastName.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
212
Designing Mappings
Joining Data
In some mappings, a condition consisting of one comparison may be sufficient to perform the join.
However, in this example, it is important that two comparisons are created:
1) FirstName in Structure1 = FirstName in Structure 2
2) LastName in Structure 1 = LastName in Structure 2.
When multiple conditions are defined, all of them must be true in order for the join to tak e place.
Therefore, in this example, a join will happen only when both comparisons are true (which is the
intended behaviour). Otherwise, if only one of the comparisons above were defined, a join could
happen for persons that have the same first name but different last names.
Step 4: Map the Join component to the target schema
Now that the two structures are joined, you can define which items of the joined structure should
be mapped to the target. To do this, create connections from items of both joined structures to
the target component, as shown below. The connection between joined and Row has the
following purpose: whenever the join condition is satisfied, it creates a new Row item in the target.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Joining Data
213
To preview the mapping output, click the Output tab. As expected, each person record (<Row>)
now includes the full address details, joined from two different sources.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
214
Designing Mappings
Using Value-Maps
5.11 Using Value-Maps
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 Filters and Conditions.
To use a Value-Map component:
1.
Select the menu option Insert | Value-Map, or click the Value-Map icon
bar.
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.
5.
Enter the input value that you want to transform, in the Weekday input column.
Enter the output value you want to transform that value to, in the Day of the week
Altova MapForce 2017 Professional Edition
in the icon
© 2017 Altova Gmb H
Designing Mappings
6.
7.
8.
Using Value-Maps
215
column.
Simply type in the (new entry) input field to enter a new value pair.
Click the datatype combo box, below the column header to select the input and output
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.
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.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
216
Designing Mappings
Using Value-Maps
What this mapping does:
Extracts the day of the week from the Date item in the data source, converts the numerical 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 "Tuesday", then the corresponding output "Prepare Financial
Reports" is mapped to the Notes 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"
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Using Value-Maps
217
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".
5.11.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.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
218
Designing Mappings
Using Value-Maps
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 substitutemissing 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 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
4.
Using Value-Maps
219
Click the Output 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 original node and data from
the Title node, and passes it on through the replace-with parameter, and then on to
Title2.
5.11.2
Value-Map component properties
Actions:
Click the insert icon to insert a new row before the currently active one.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
220
Designing Mappings
Using Value-Maps
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.
Input and output datatypes
The input and result datatypes are automatically checked when a selection is made using the
combo box. If a mismatch occurs, then the respective fields are highlighted and the OK button is
disabled. Change the datatype to one that is supported.
In the screenshot below a boolean and string have been selected.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
© 2017 Altova Gmb H
Using Value-Maps
221
Altova MapForce 2017 Professional Edition
222
Designing Mappings
Adding Exceptions
5.12 Adding Exceptions
An exception is a special component type that enables you to stop the mapping process and
display an error when a condition returned by a filter occurs. You can add an exception when your
mapping includes a filter that checks for a true/false condition (see Filters and Conditions). For
example, you may want to throw an exception if the value of some mapping item is greater than
some custom threshold.
To add an exception to the mapping:
1.
2.
3.
4.
Note:
On the Insert menu, click Exception.
Click the Insert Exception (
) toolbar button.
Connect the throw input of the exception either to an on-true or on-false output of a
filter.
Optionally, connect the error-text input of the exception to another component (typically,
a constant) that supplies the text of the error when this exception is thrown.
Both the on-true and on-false outputs of the filter must be connected. Specifically, one
of these outputs must be connected directly to the exception (without any intermediary
functions or components). The other output must be connected to the target component,
either directly, or through other intermediary components.
When the mapping encounters an exception, you are notified about it as follows:
In MapForce, the Messages window displays an error, and the exception text (in this
case, "Expense limit exceeded").
If the mapping language is XSLT 2.0 or XQuery, an "Execution failed" error appears in the
Messages window, and the respective XSLT2 or XQuery tab is opened. The error line is
highlighted in the Messages window.
If you run the mapping with MapForce Server, the error "Exception was thrown!" is
returned, followed by the custom exception text you have defined in MapForce.
If you run the mapping from the generated C#, C++, or Java code, the error "USER
EXCEPTION" is returned, followed by the custom exception text you have defined in
MapForce.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
5.12.1
Adding Exceptions
223
Example: Exception on "Greater Than" Condition
This example illustrates a mapping that throws an exception when a "Greater Than" condition
occurs. The sample mapping accompanying this example can be found at: <Documents>
\Altova\MapForce2017\MapForceExamples\ExpenseLimit.mfd.
This mapping throws an exception whenever the expense item in the source XML instance has a
value greater than 200. The value "200" is provided by a constant. The less function is then used
to compare the two values. If the value of expense is less than 200, then its parent, the
expense-item, is passed on to the filter, and no exception is thrown. Otherwise, an exception is
thrown, with the custom text "Expense limit exceed".
As shown above, the exception is identified by the
icon and it consists of two items: throw
and error-text. The throw item must be connected to the on-false or on-true output of a filter.
The error-text is connected to a constant which provides the custom text of the exception.
Importantly, both outputs of the filter are connected; otherwise, the exception would not be
thrown. In this particular example, the on-false output is connected to the exception, while the
on-true output is connected to the target component.
5.12.2
Example: Exception When Node Does Not Exist
This example illustrates how to throw an exception when a node in the source XML schema does
not exist. For the sake of simplicity, this example uses the same XML schema both as source
and target component.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
224
Designing Mappings
Adding Exceptions
To add the source schema to the mapping:
1.
2.
3.
On the Insert menu, click XML Schema/File, and browse for <Documents>\Altova
\MapForce2017\MapForceExamples\BookList.xsd.
When prompted to provide an instance file, click Skip.
When prompted to select a schema root element, select BookList as root element.
To add the target schema, follow the same steps. Then, using the corresponding commands from
Insert menu (or the corresponding toolbar buttons), add the following:
A Filter: Nodes/Rows component (see also Filters and Conditions)
An intermediate variable of simple type "string"
A constant with the text "No year defined!"
An exception
Finally, drag the exists function from the Libraries window into the mapping area, and make the
connections as illustrated below.
According to the XML schema, all attributes of the Book element are optional, except the book
title. Therefore, the "Year" attribute may or may not exist in a valid XML instance. The goal of the
mapping is to process successfully an XML instance where the "Year" attribute exists for each
book. Otherwise, the mapping must throw an exception.
To test the successful execution of the mapping:
1.
2.
Double-click the header of the source component and, next to Input XML file, browse for
the following file: <Documents>\Altova\MapForce2017\MapForceExamples
\BookList.xml.
Click the Output button to run the mapping.
To test the exception:
1.
2.
3.
Create, in the same directory, a copy of the BookList.xml file called
BookListInvalid.xml.
Modify it so as to remove the "Year" attribute from a Book element.
Double-click the header of the source component, and, next to Input XML file, browse
for the BookListInvalid.xml file.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
4.
Adding Exceptions
225
Click the Output button to run the mapping.
Let's now have a closer look at how the mapping works. Unlike the previous example, this
mapping uses an intermediate variable (see also Using Variables). The purpose of the
intermediate variable is to temporarily store the value of the "Year" attribute, when it exists, in the
context of each book, and then write it to the target file. The Year output of the source component
was deliberately not connected directly to the Year input of the target component, since the
"Year" value may be missing, and we want to check for this case.
Connection A ensures that a book in the target instance is created for each book in the source
instance. Connections B and C ensure that the "Title" and "Author" are copied from the source to
the target, for each book.
Connection D passes the Book to the filter, conditionally. Namely, the filter gets only those books
which have a "Year" attribute. To make this happen, connection E triggers the exists function to
check for the existence of the "Year" attribute. Connection F passes the function result (true or
false) to the filter. If the result is true, the "Year" attribute exists, and the book is passed on to
the filter. Also, the variable is populated with the year value (through connection H).
Notice that the filter was not connected directly to the Year output of the source component.
Had we done so, the filter would filter the Year by its own existence, which is not meaningful,
and the exception would never be thrown.
Connection G ensures that the variable is computed whenever the filter condition is true (that is,
whenever the "Year" attribute exists). As already mentioned, the value of the variable is supplied
by the connection H from the Year output of the source component. The connection I then
passes the value to the target component.
Connection J is there because the exception must be connected either to an on-false or on-true
output of a filter, according to the rules. Finally, connection K passes the custom error text from
the constant to the exception component.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
226
Designing Mappings
Parsing and Serializing Strings
5.13 Parsing and Serializing Strings
String parsing and serialization is an advanced mapping technique that enables you to configure
the component to either parse data from a string, or serialize data to a string. This technique can
be regarded as an alternative to reading data from (or writing data to) files. MapForce components
which parse strings or serialize data to strings can be useful in a variety of situations, for
example:
You need to insert structures such as XML into database fields.
You need to convert XML fragments stored in database fields into standalone XML files.
You have legacy data stored as text (for example, fixed-length content in a single
database field), and you would like to convert this data into a fully sortable, field-based
structure
String parsing and serialization is available for the following MapForce component types:
Text (CSV, fixed-length field text)
XML schema files
String parsing and serialization is supported in MapForce target languages as follows.
Language
Reading
Writing
BUILT-IN (preview the
mapping transformation)
Yes
Yes
BUILT-IN (run the MapForce
Server execution file)
Yes
Yes
This section includes the following topics:
About the Parse/Serialize Component
Example: Serialize to String (XML to Database)
5.13.1
About the Parse/Serialize Component
A Parse/Serialize component in MapForce is a hybrid component which is neither a source nor a
target component. Given the role they play in the mapping design, such components must be
placed in between other source and target components.
You can use a "Parse/Serialize String" component for string parsing when, for some reason, you
need to convert a string that has structure (for example, some XML stored as string in a database)
into another format. Parsing data from the source string to the "Parse/Serialize" component
means that the source string is turned into a MapForce structure, and, thus, you get access to
any element or attribute of the source XML stored as string.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Parsing and Serializing Strings
227
Generic "Parse String" component
The diagram above illustrates the typical structure of a MapForce component which parses a
string. Note that the "Parse/Serialize String" component is placed in between the source and
target of the mapping. What this component does is accept some string structure as input, by
means of a single MapForce connector which is connected to its top String node. The output
structure can be any of the data targets supported by MapForce.
When you serialize data from a component to string, the reverse happens. Specifically, the entire
structure of the MapForce component becomes a string structure which you can further
manipulate as necessary. For example, this enables you to write an XML file (or XML fragment) to
a database field or to a single cell of an Excel spreadsheet.
Generic "Serialize to String" component
The diagram above illustrates a generic MapForce "Serialize to String" component. What this
component does is accept as input any data source supported by MapForce (by means of
standard MapForce connectors). The output structure is a string which you can pass further by
means of a single MapForce connector drawn from the top String node of the component to a
target component item (for example, a spreadsheet cell). For an example, see Example: Serialize
to String (XML to Database).
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
228
Designing Mappings
Parsing and Serializing Strings
You can designate a component for string parsing or serialization at any time from the mapping
window. To do so, click the File/String (
) button adjacent to the root node, and then
select the desired option.
Changing the component mode
Note:
A "Parse/Serialize String" component cannot read data from a string and write to a string
simultaneously. Therefore, the root node can have either an incoming connector or an
outgoing connector (not both). An error will be generated if you attempt to use the same
component for both operations.
When you designate a component for string parsing or serialization, the appearance of component
changes as follows:
The component gets the parse or serialize prefix in the title.
The title bar has yellow background color, similar to function components.
The top node begins with the String: prefix and is identified by the icon.
If the component parses a string, the output connector from the root node is not
meaningful and thus it is not available.
If the component serializes to a string, the input connector to the root node is not
meaningful and thus it is not available.
When a component is in "Parse/Serialize String" mode, you can change its settings in a similar
way as if it were in a file-based mode (see Changing the Component Settings). Note that not all
component settings are available when a component is in either "Parse" or "Serialize" mode.
5.13.2
Example: Serialize to String (XML to Database)
This example walks you through the steps required to create a mapping design which serializes
data to a string. The example is accompanied by a sample file. If you want to look at the sample
file before starting this example, you can open it from the following path: <Documents>\Altova
\MapForce2017\MapForceExamples\Tutorial\SerializeToString.mfd.
Let's assume you have an XML file (and its related schema) which consists of multiple <Person>
elements. Each <Person> element describes a person's first name, last name, job title, phone
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Parsing and Serializing Strings
229
extension, and email address, as follows:
<Person>
<First>Joe</First>
<Last>Firstbread</Last>
<Title>Marketing Manager Europe</Title>
<PhoneExt>621</PhoneExt>
<Email>j.firstbread@nanonull.com</Email>
</Person>
Your goal is to extract each <Person> element from the XML file and insert it literally (including
XML tags) as a new database record in the PEOPLE table of a SQLite database. The PEOPLE table
contains only two columns: ID and PERSON. Its full definition is as follows:
CREATE TABLE PEOPLE (ID INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, PERSON
TEXT);
After the mapping is executed, the expected result is that the PEOPLE table will have the same
number of rows as the number of <Person> elements in the XML file.
To achieve the goal, do the following:
1.
2.
3.
4.
Add to the mapping area the source XML component (use the Insert | XML Schema/File
menu command). The sample file is available at: <Documents>\Altova\MapForce2017
\MapForceExamples\Tutorial\MFCompany.xml.
Duplicate (copy-paste) the XML component.
On the duplicated XML component, click
, and then select Serialize XML to
Strings.
Right-click the duplicated component and select Change Root Element from the
context menu. Then change the root element to <Person>.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
230
Designing Mappings
Parsing and Serializing Strings
In general, you can change the root element to any element that has a global (not
local) declaration in the XML schema. Any elements that are not defined globally in
your schema are not listed in the "Select Root Element" dialog box.
5.
Double-click the component and disable the Write XML Declaration option. This
prevents the XML declaration from being written for each <Person> element.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Parsing and Serializing Strings
6.
Add to the mapping area the target SQLite database component, from the following path:
<Documents>\Altova\MapForce2017\MapForceExamples\Tutorial\\dbserialize.db.
(To add the database component, use the Insert | Database menu command, see also
Connecting to a Database ). When prompted to insert a database object, select the
PEOPLE table.
7.
Link the components as shown below. On the left side of the mapping, the <Person>
element maps to the serialization component. On the right side of the mapping, the
serialized string value is inserted into the PERSON column of the PEOPLE database table.
Finally, the connector drawn from <Person> to PEOPLE table instructs MapForce to create
a new record for each <Person> element encountered.
© 2017 Altova Gmb H
231
Altova MapForce 2017 Professional Edition
232
Designing Mappings
8.
Parsing and Serializing Strings
Click the A:In button on the database component, and instruct MapForce to perform the
following actions every time when the mapping transformation runs:
a. Delete all records from the table;
b. Increment the value of ID by 1.
Observe the max()+1 action selected for the ID column. This instructs MapForce to
analyze what is the maximum ID value already existing in the database, and insert
the next available integer, incremented by 1.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Parsing and Serializing Strings
233
You have now created a mapping design which serializes data to string. If you click the Output
tab, the preview SQL query indicates that separate records will be inserted into the database for
each <Person> element in the XML file, which was the goal of this mapping.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
234
Designing Mappings
Mapping Node Names
5.14 Mapping Node Names
Most of the time when you create a mapping with MapForce, the goal is to read values from a
source and write values to a target. However, there might be cases when you want to access not
only the node values from the source, but also the node names. For example, you might want to
create a mapping which reads the element or attribute names (not values) from a source XML and
converts them to element or attribute values (not names) in a target XML.
Consider the following example: you have an XML file that contains a list of products. Each
product has the following format:
<product>
<id>1</id>
<color>red</color>
<size>10</size>
</product>
Your goal is to convert information about each product into name-value pairs, for example:
<product>
<attribute name="id" value="1" />
<attribute name="color" value="red" />
<attribute name="size" value="10" />
</product>
For such scenarios, you would need access to the node name from the mapping. With dynamic
access to node names, which the subject of this topic, you can perform data conversions such as
the one above.
Note:
You can also perform the transformation above by using the node-name and staticnode-name core library functions. However, in this case, you need to know exactly what
element names you expect from the source, and you need to connect every single such
element manually to the target. Also, these functions might not be sufficient, for example,
when you need to filter or group nodes by name, or when you need to manipulate the data
type of the node from the mapping.
Accessing node names dynamically is possible not only when you need to read node names, but
also when you need to write them. In a standard mapping, the name of attributes or elements in a
target is always known before the mapping runs; it comes from the underlying schema of the
component. With dynamic node names, however, you can create new attributes or elements
whose name is not known before the mapping runs. Specifically, the name of the attribute or
element is supplied by the mapping itself, from any source supported by MapForce.
For dynamic access to a node's children elements or attributes to be possible, the node
must actually have children elements or attributes, and it must not be the XML root node.
Dynamic node names are supported when you map to or from the following component types:
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Mapping Node Names
235
XML
CSV/FLF*
* Requires MapForce Professional or Enterprise Edition.
Note:
In case of CSV/FLF, dynamic access implies access to "fields" instead of "nodes", since
CSV/FLF structures do not have "nodes".
When the mapping target is a CSV or FLF (fixed-length field) file, the fields must be defined in
the component settings (and it is not possible to change the name, order, or number of the
target fields). Unlike XML, the format of text files is fixed, so only the actual field value can be
manipulated, not the field name, number or order.
Dynamic node names are supported in any of the following mapping languages: Built-In*, XSLT2,
XQuery*, C#*, C++*, Java*.
* Requires MapForce Professional or Enterprise Edition.
For information about how dynamic node names work, Getting Access to Node Names. For a
step-by-step mapping example, see Example: Map Element Names to Attribute Values.
5.14.1
Getting Access to Node Names
When a node in an XML component (or a field in a CSV/FLF component) has children nodes, you
can get both the name and value of each child node directly on the mapping. This technique is
called "dynamic node names". "Dynamic" refers to the fact that processing takes place "on the
fly", during mapping runtime, and not based on the static schema information which is known
before the mapping runs. This topic provides details on how to enable dynamic access to node
names and what you can do with it.
When you read data from a source, "dynamic node names" means that you can do the following:
Get a list of all children nodes (or attributes) of a node, as a sequence. In MapForce,
"sequence" is a list of zero or more items which you can connect to a target and create
as many items in the target as there are items in the source. So, for example, if a node
has five attributes in the source, you could create five new elements in the target, each
corresponding to an attribute.
Read not only the children node values (as a standard mapping does), but also their
names.
When you write data to a target, "dynamic node names" means that you can do the following:
Create new nodes using names supplied by the mapping (so-called "dynamic" names),
as opposed to names supplied by the component settings (so-called "static" names).
To illustrate dynamic node names, this topic makes use of the following XML schema:
<Documents>\Altova\MapForce2017\MapForceExamples\Tutorial\Products.xsd. This
schema is accompanied by a sample instance document, Products.xml. To add both the
schema and the instance file to the mapping area, select the Insert | XML Schema/File menu
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
236
Designing Mappings
Mapping Node Names
command and browse for <Documents>\Altova\MapForce2017\MapForceExamples\Tutorial
\Products.xml. When prompted to select a root element, choose products.
To enable dynamic node names for the product node, right-click it and select one of the following
context menu commands:
Show Attributes with Dynamic Name, if you want to get access to the node's
attributes
Show Child Elements with Dynamic Name, if you want to get access to the node's
children elements
Fig. 1
Enab ling dynamic node names (for child elements)
Note:
The commands above are available only for nodes that have children nodes. Also, the
commands are not available for root nodes.
When you switch a node into dynamic mode, a dialog box such as the one below appears. For
the purpose of this topic, set the options as shown below; these options are further discussed in
Accessing Nodes of Specific Type.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Fig. 2
Mapping Node Names
237
"Dynamically Named Children Settings" dialog b ox
Fig. 3 illustrates how the component looks when dynamic node names are enabled for the
product node. Notice how the appearance of the component has now significantly changed.
Fig.3
Enab led dynamic node names (for elements)
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
238
Designing Mappings
Mapping Node Names
To switch the component back to standard mode, right-click the product node, and disable the
option Show Child Elements with Dynamic Name from the context menu.
The image below shows how the same component looks when dynamic access to attributes of a
node is enabled. The component was obtained by right-clicking the product element, and
selecting Show Attributes with Dynamic Name from the context menu.
Fig. 4
Enab led dynamic node names (for attrib utes)
To switch the component back to standard mode, right-click the product node, and disable the
option Show Attributes with Dynamic Name from the context menu.
As illustrated in Fig. 3 and Fig. 4, the component changes appearance when any node (in this
case, product) is switched into "dynamic node name" mode. The new appearance opens
possibilities for the following actions:
Read or write a list of all children elements or attributes of a node. These are provided by
the element() or attribute() item, respectively.
Read or write the name of each child element or attribute. The name is provided by the
node-name() and local-name() items.
In case of elements, read or write the value of each child element, as specific data type.
This value is provided by the type cast node (in this case, the text() item). Note that
only elements can have type cast nodes. Attributes are treated always as "string" type.
Group or filter child elements by name. For an example, see Example: Group and Filter
Nodes by Name.
The node types that you can work with in "dynamic node name" mode are described below.
element()
This node has different behaviour in a source component compared to a target component. In a
source component, it supplies the child elements of the node, as a sequence. In Fig.3,
element() provides a list (sequence) of all children elements of product. For example, the
sequence created from the following XML would contain three items (since there are three child
elements of product):
<product>
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Mapping Node Names
239
<id>1</id>
<color>red</color>
<size>10</size>
</product>
Note that the actual name and type of each item in the sequence is provided by the node-name()
node and the type cast node, respectively (discussed below). To understand this, imagine that
you need to transform data from a source XML into a target XML as follows:
Fig. 6
Mapping XML element names to attrib ute values (requirement)
The mapping which would achieve this goal looks as follows:
Fig. 7
Mapping XML element names to attrib ute values (in MapForce)
The role of element() here is to supply the sequence of child elements of product, while nodename() and text() supply the actual name and value of each item in the sequence. This
mapping is accompanied by a tutorial sample and is discussed in more detail in Example: Map
Element Names to Attribute Values.
In a target component, element() does not create anything by itself, which is an exception to the
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
240
Designing Mappings
Mapping Node Names
basic rule of mapping "for each item in the source, create one target item". The actual elements
are created by the type cast nodes (using the value of node-name()) and by name test nodes
(using their own name).
attribute()
As shown in Fig. 4, this item enables access to all attributes of the node, at mapping runtime. In
a source component, it supplies the attributes of the connected source node, as a sequence. For
example, in the following XML, the sequence would contain two items (since product has two
attributes):
<product id="1" color="red" />
Note that the attribute() node supplies only the value of each attribute in the sequence, always
as string type. The name of each attribute is supplied by the node-name() node.
In a target component, this node processes a connected sequence and creates an attribute value
for each item in the sequence. The attribute name is supplied by the node-name(). For example,
imagine that you need to transform data from a source XML into a target XML as follows:
Fig. 8
Mapping attrib ute values to attrib ute names (requirement)
The mapping which would achieve this goal looks as follows:
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Mapping Node Names
Fig. 9
Mapping attrib ute values to attrib ute names (in MapForce)
Note:
This transformation is also possible without enabling dynamic access to a node's
attributes. Here it just illustrates how attribute() works in a target component.
241
If you want to reconstruct this mapping, it uses the same XML components as the
ConvertProducts.mfd mapping available in the <Documents>\Altova\MapForce2017
\MapForceExamples\Tutorial\ folder. The only difference is that the target has now become the
source, and the source has become the target. As input data for the source component, you will
need an XML instance that actually contains attribute values, for example:
<?xml version="1.0" encoding="UTF-8"?>
<products>
<product>
<attribute name="id" value="1"/>
<attribute name="color" value="red"/>
<attribute name="size" value="big"/>
</product>
</products>
Note that, in the code listing above, the namespace and schema declaration have been omitted,
for simplicity.
node-name()
In a source component, node-name() supplies the name of each child element of element(), or
the name of each attribute of attribute(), respectively. By default, the supplied name is of type
xs:QName. To get the name as string, use the local-name() node (see Fig. 3), or use the
function QName-as-string.
In a target component, node-name() writes the name of each element or attribute contained in
element() or attribute().
local-name()
This node works in the same way as node-name(), with the difference that the type is xs:string
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
242
Designing Mappings
Mapping Node Names
instead of xs:QName.
Type cast node
In a source component, the type cast node supplies the value of each child element contained in
element(). The name and structure of this node depends on the type selected from the
"Dynamically Named Children Settings" dialog box (Fig. 2).
To change the type of the node, click the Change Selection (
) button and select a type from
the list of available types, including a schema wildcard (xs:any). For more information, see
Accessing nodes of specific type.
In a target component, the type cast node writes the value of each child element contained in
element(), as specific data type. Again, the desired data type can be selected by clicking the
Change Selection (
) button.
Name test nodes
In a source component, name test nodes provide a way to group or filter child elements from a
source instance by name. You may need to filter child elements by name in order to ensure that
the mapping accesses the instance data using the correct type (see Accessing Nodes of Specific
Type). For an example, see Example: Group and Filter Nodes by Name.
In general, the name test nodes work almost like normal element nodes for reading and writing
values and subtree structures. However, because the mapping semantics is different when
dynamic access is enabled, there are some limitations. For example, you cannot concatenate the
value of two name test nodes.
On the target side, name test nodes create as many elements in the output as there are items in
the connected source sequence. Their name overrides the value mapped to node-name().
If necessary, you can hide the name test nodes from the component. To do this, click the
Change Selection (
) button next to the element() node. Then, in the "Dynamically Named
Children Settings" dialog box (Fig. 2), clear the Show name test nodes... check box.
5.14.2
Accessing Nodes of Specific Type
As mentioned in the previous section, Getting Access to Node Names, you can get access to all
child elements of a node by right-clicking the node and selecting the Show Child Elements with
Dynamic Name context menu command. At mapping runtime, this causes the name of each
child element to be accessible through the node-name() node, while the value—through a special
type cast node. In the image below, the type cast node is the text() node.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Mapping Node Names
243
Importantly, the data type of each child element is not known before the mapping runtime.
Besides, it may be different for each child element. For example, a product node in the XML
instance file may have a child element id of type xs:integer and a child element size of type
xs:string. To let you access the node content of a specific type, the dialog box shown below
opens every time when you enable dynamic access to a node's child elements. You can also
open this dialog box at any time later, by clicking the Change Selection (
) button next to
the element() node.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
244
Designing Mappings
Mapping Node Names
"Dynamically Named Children Settings" dialog b ox
To access the content of each child element at mapping runtime, you have several options:
1.
2.
3.
Access the content as string. To do this, select the text() check box on the dialog box
above. In this case, a text() node is created on the component when you close the
dialog box. This option is suitable if the content is of simple type (xs:int, xs:string,
etc.) and is illustrated in the Example: Map Element Names to Attribute Values. Note
that a text() node is displayed only if a child node of the current node can contain text.
Access the content as a particular complex type allowed by the schema. When custom
complex types defined globally are allowed by the schema for the selected node, they are
also available in the dialog box above, and you can select the check box next to them. In
the image above, there are no complex types defined globally by the schema, so none
are available for selection.
Access the content as any type. This may be useful in advanced mapping scenarios (see
"Accessing deeper structures" below). To do this, select the check box next to
xs:anyType.
Be aware that, at mapping runtime, MapForce (through the type cast node) has no
information as to what the actual type of the instance node is. Therefore, your mapping must
access the node content using the correct type. For example, if you expect that the node of
a source XML instance may have children nodes of various complex types, do the following:
a) Set the type cast node to be of the complex type that you need to match (see item 2 in
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Mapping Node Names
245
the list above).
b) Add a filter to read from the instance only the complex type that you need to match. This
technique is illustrated in Example: Group and Filter Nodes by Name.
Accessing deeper structures
It is possible to access nodes at deeper levels in the schema than the immediate children of a
node. It is useful for advanced mapping scenarios. In simple mappings such as Example: Map
Element Names to Attribute Values, you don't need this technique because the mapping
accesses only the immediate children of an XML node. However, if you need to access deeper
structures dynamically, such as "grandchildren", "grand-grandchildren", and so on, this is
possible as shown below.
1.
2.
3.
4.
5.
6.
Create a new mapping.
On the Insert menu, click Insert XML Schema/File and browse for the XML instance file
(in this example, the Articles.xml file from the <Documents>\Altova\MapForce2017
\MapForceExamples\Tutorial\ folder).
Right-click the Articles node and select the Show Child Elements with Dynamic
Name context command.
Select xs:anyType from the "Dynamically Named Children Settings" dialog box.
Right-click the xs:anyType node and select again the Show Child Elements with
Dynamic Name context command.
Select text() from the "Dynamically Named Children Settings" dialog box.
In the component above, notice there are two element() nodes. The second element() node
provides dynamic access to grandchildren of the <Articles> node in the Articles.xml instance.
<?xml version="1.0" encoding="UTF-8"?>
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
246
Designing Mappings
Mapping Node Names
<Articles xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="Articles.xsd">
<Article>
<Number>1</Number>
<Name>T-Shirt</Name>
<SinglePrice>25</SinglePrice>
</Article>
<Article>
<Number>2</Number>
<Name>Socks</Name>
<SinglePrice>2.30</SinglePrice>
</Article>
<Article>
<Number>3</Number>
<Name>Pants</Name>
<SinglePrice>34</SinglePrice>
</Article>
<Article>
<Number>4</Number>
<Name>Jacket</Name>
<SinglePrice>57.50</SinglePrice>
</Article>
</Articles>
Articles.xml
For example, to get "grandchildren" element names (Number, Name, SinglePrice), you would
draw a connection from the local-name() node under the second element() node to a target
item. Likewise, to get "grandchildren" element values (1, T-Shirt, 25), you would draw a
connection from the text() node.
Although not applicable to this example, in real-life situations, you can further enable dynamic
node names for any subsequent xs:anyType node, so as to reach even deeper levels.
Note the following:
The
button allows you to select any derived type from the current schema and
display it in a separate node. This may only be useful if you need to map to or from
derived schema types (see Derived XML Schema Types).
The Change Selection (
) button next to an element() node opens the
"Dynamically Named Children Settings" dialog box discussed in this topic.
The Change Selection (
) button next to xs:anyAttribute allows you to select any
attribute defined globally in the schema. Likewise, the Change Selection (
) button
next to xs:any element allows you to select any element defined globally in the schema.
This works in the same way as mapping to or from schema wildcards (see also
Wildcards - xs:any / xs:anyAttribute). If using this option, make sure that the selected
attribute or element can actually exist at that particular level according to the schema.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
5.14.3
Mapping Node Names
247
Example: Map Element Names to Attribute Values
This example shows you how to map element names from an XML document to attribute values in
a target XML document. The example is accompanied by a sample mapping, which is available at
the following path: <Documents>\Altova\MapForce2017\MapForceExamples\Tutorial
\ConvertProducts.mfd.
To understand what the example does, let's assume you have an XML file that contains a list of
products. Each product has the following format:
<product>
<id>1</id>
<color>red</color>
<size>10</size>
</product>
Your goal is to convert information about each product into name-value pairs, for example:
<product>
<attribute name="id" value="1" />
<attribute name="color" value="red" />
<attribute name="size" value="10" />
</product>
To perform a data mapping such as the one above with minimum effort, this example uses a
MapForce feature known as "dynamic access to node names". "Dynamic" means that, when the
mapping runs, it can read the node names (not just values) and use these names as values. You
can create the required mapping in a few simple steps, as shown below.
Step 1: Add the source XML component to the mapping
On the Insert menu, click XML Schema/File, and browse for the following file:
<Documents>\Altova\MapForce2017\MapForceExamples\Tutorial\Products.xml.
This XML file points to the Products.xsd schema located in the same folder.
Step 2: Add the target XML component to the mapping
On the Insert menu, click XML Schema/File, and browse for the following schema file:
<Documents>\Altova\MapForce2017\MapForceExamples\Tutorial
\ProductValuePairs.xsd. When prompted to supply an instance file, click Skip. When
prompted to select a root element, select products as root element.
At this stage, the mapping should look as follows:
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
248
Designing Mappings
Mapping Node Names
Step 3: Enable dynamic access to child nodes
1.
2.
Right-click the products node on the source component, and select Show Child
Elements with Dynamic Name from the context menu.
In the dialog box which opens, select text() as type. Leave other options as is.
Notice that a text() node has been added on the source component. This node will supply the
content of each child item to the mapping (in this case, the value of "id", "color", and "size").
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Mapping Node Names
249
Step 4: Draw the mapping connections
Finally, draw the mapping connections A, B, C, D as illustrated below. Optionally, double-click
each connection, starting from the top one, and enter the text "A", "B", "C", and "D", respectively,
into the Description box.
ConvertProducts.mfd
In the mapping illustrated above, connection A creates, for each product in the source, a product
in the target. So far, this is a standard MapForce connection that does not address the node
names in any way. The connection B, however, creates, for each encountered child element of
product, a new element in the target called attribute.
Connection B is a crucial connection in the mapping. To reiterate the goal of this connection,
it carries a sequence of child elements of product from the source to the target. It does not
carry the actual names or values. Therefore, it must be understood as follows: if the source
element() has N child elements, create N instances of that item in the target. In this
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
250
Designing Mappings
Mapping Node Names
particular case, product in the source has three children elements (id, color and size).
This means that each product in the target will have three child elements with the name
attribute.
Although not illustrated in this example, the same rule is used to map child elements of
attribute(): if the source attribute() item has N child attributes, create N instances of that
item in the target.
Next, connection C copies the actual name of each child element of product to the target
(literally, "id", "color", and "size").
Finally, connection D copies the value of each child element of product, as string type, to the
target.
To preview the mapping output, click the Output tab and observe the generated XML. As
expected, the output contains several products whose data is stored as name-value pairs, which
was the intended goal of this mapping.
<?xml version="1.0" encoding="UTF-8"?>
<products xsi:noNamespaceSchemaLocation="ProductValuePairs.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<product>
<attribute name="id" value="1"/>
<attribute name="color" value="red"/>
<attribute name="size" value="10"/>
</product>
<product>
<attribute name="id" value="2"/>
<attribute name="color" value="blue"/>
<attribute name="size" value="20"/>
</product>
<product>
<attribute name="id" value="3"/>
<attribute name="color" value="green"/>
<attribute name="size" value="30"/>
</product>
</products>
Generated mapping output
5.14.4
Example: Group and Filter Nodes by Name
This example shows you how to design a mapping that reads key-value pairs from an XML
property list (or XML plist) and writes them to a CSV file. (XML property lists represent a way of
storing OS X and iOS object information in XML format, see https://developer.apple.com/library/
mac/documentation/Cocoa/Conceptual/PropertyLists/UnderstandXMLPlist/
UnderstandXMLPlist.html.) The example is accompanied by a mapping sample which is available
at the following path: <Documents>\Altova\MapForce2017\MapForceExamples\Tutorial
\ReadPropertyList.mfd.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Mapping Node Names
251
The code listing below represents the source XML file.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist SYSTEM "https://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>First Name</key>
<string>William</string>
<key>Last Name</key>
<string>Shakespeare</string>
<key>Birthdate</key>
<integer>1564</integer>
<key>Profession</key>
<string>Playwright</string>
<key>Lines</key>
<array>
<string>It is a tale told by an idiot,</string>
<string>Full of sound and fury, signifying nothing.</string>
</array>
</dict>
</plist>
The goal of the mapping is to create a new line in the CSV file from certain key-value pairs found
under <dict> node in the property list file. Specifically, the mapping must filter only <key> <string> pairs. Other key-value pairs (for example, <key> - <integer>) must be ignored. In the
CSV file, the line must store the name of the property, separated from the value of the property by
a comma. In other words, the output must look as follows:
First Name,William
Last Name,Shakespeare
Profession,Playwright
To achieve this goal, the mapping uses dynamic access to all children nodes of the dict node.
Secondly, the mapping uses the group-starting-with function to group the key-value pairs retrieved
from the XML file. Finally, the mapping uses a filter to filter only those nodes where the node
name is "string".
The following steps show how the required mapping can be created.
Step 1: Add the source XML component to the mapping
1.
2.
Set the mapping transformation language to BUILT-IN (see Selecting a Transformation
Language).
On the Insert menu, click XML Schema/File, and browse for the following file:
<Documents>\Altova\MapForce2017\MapForceExamples\Tutorial\plist.xml. This
XML file points to the plist.dtd schema located in the same folder.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
252
Designing Mappings
Mapping Node Names
Step 2: Add the target CSV component to the mapping
1.
2.
3.
On the Insert menu, click Text File. When prompted, select the Use simple
processing for standard CSV... option.
Add a CSV field to the component, by clicking Append field.
Double-click the name of each field, and enter "Key" as name of the first field, and
"Value" as name of the second field. The "Key" field will store the name of the property,
while the "Value" field will store the property value. For more information about CSV
components, see CSV and Text Files.
Step 3: Add the filter and functions
1.
2.
3.
4.
Drag the equal, exists and group-starting-with functions from the Libraries window
into the mapping. For general information about functions, see Working with Functions.
To add the filter, click the Insert menu, and then click Filter: Nodes/Rows. For general
information about filters, see Filters and Conditions.
On the Insert menu, click Constant, and then enter the text "string".
In the source component, right-click the dict node select Show Child Elements with
Dynamic Name from the context menu. On the "Dynamically Named Children Settings"
dialog box, make sure that the check box Show name test nodes to filter or create
elements by fixed node name is selected.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
5.
Mapping Node Names
253
Draw the connections as shown below.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
254
Designing Mappings
Mapping Node Names
ReadPropertyList.mfd
The mapping explained
The element() item on the source component provides all children of the dict node, as a
sequence, to the group-starting-with function. The group-starting-with function creates a
new group whenever a node with the name key is encountered. The exists function checks for
this condition and returns the result as Boolean true/false to the grouping function.
For each group, the filter checks if the name of the current node is equal to "string", with the help
of the equal function. The name itself is read from the local-name(), which supplies the node's
name as a string.
The connections to the target component have the following role:
Only when the filter condition is true, a new row is created in the target CSV.
Key (property name) is taken from the value of the key element in the source.
Value (property value) is taken from the string name test node.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Mapping Rules and Strategies
255
5.15 Mapping Rules and Strategies
MapForce generally maps data in an intuitive way, but you may come across situations where the
resulting output seems to have too many, or too few items. This topic is intended to help you
avoid such mapping problems.
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 (for example, string or integer)
and the target node accepts simple content, then MapForce copies the content to the target node
and, if necessary, converts the data type.
This generally holds true for all connections, with the following exceptions:
A target XML root element is always created once and only once. If you connect a
sequence to it, only the contents of the element will be repeated, but not the root element
itself, and the result might 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 to the root element. If what you want to achieve is creating multiple output files,
connect the sequence to the "File" node instead, via some function that generates file
names.
Some nodes accept a single value, not a sequence (for example, XML attributes,
database fields , and output components in user-defined functions).
The "context" and "current" items
MapForce displays the structure of a schema, database 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.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
256
Designing Mappings
Mapping Rules and Strategies
PersonListByBranchOffice.mfd
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
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
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Mapping Rules and Strategies
257
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":
Sequences
MapForce displays the structure of a schema, database 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 (or database)
a sequence of zero to multiple instance nodes of the input file (or database)
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
loops 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)
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
258
Designing Mappings
Mapping Rules and Strategies
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 or SQL-Where 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.
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). See 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 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Mapping Rules and Strategies
259
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. See also
Overriding the Mapping Context.
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.
5.15.1
Changing the Processing Order of Mapping Components
MapForce supports mappings that have several target components. Each of the target
components has a preview button allowing you to preview the mapping result for that specific
component.
If the mapping is executed from the command line or from generated code, then, regardless of the
currently active preview, the full mapping is executed and the output for each target component is
generated.
The order in which the target components are processed can be directly influenced by changing
the position of target components in the mapping window. The position of a component is defined
as its top left corner.
Target components are processed according to their Y-X position on screen, from top to bottom
and left to right.
If two components have the same vertical position, then the leftmost takes precedence.
If two component have the same horizontal position, then the highest takes precedence.
In the unlikely event that components have the exact same position, then an unique
internal component ID is automatically used, which guarantees a well-defined order but
which cannot be changed.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
260
Designing Mappings
Mapping Rules and Strategies
The screenshot below shows the tutorial sample Tut-ExpReport-multi.mfd available in the
<Documents>\Altova\MapForce2017\MapForceExamples\Tutorial\ folder. Both target
components (ExpReport-Target) have the same vertical position, and the preview button is active
on the right hand target component.
Tut-ExpReport-multi.mfd (MapForce Enterprise Edition)
Having selected XSLT2 and generated the code:
The leftmost target component is processed first and generates the ExpReport.xml file.
The component to the right of it is processed next and generates the SecondXML.xml
file.
You can check that this is the case by opening the DoTransform.bat file (in the output folder you
specified) and see the sequence the output files are generated. ExpReport-Target.xml is the
first output to be generated by the batch file, and SecondXML.xml the second.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Mapping Rules and Strategies
261
Changing the mapping processing sequence:
1.
Click the left target component and move it below the one at right.
2.
Regenerate your code and take a look at the DoTransform.bat file.
SecondXML.xml is now the first output to be generated by the batch file, and
ExpReport-Target.xml the second.
Chained mappings
The same processing sequence as described above is followed for chained mappings. The
chained mapping group is taken as one unit however. Repositioning the intermediate or final target
component of a single chained mapping has no effect on the processing sequence.
Only if multiple "chains" or multiple target components exist in a mapping does the position of
the final target components of each group determine which is processed first.
If two final target components have the same vertical position, then the leftmost takes
precedence.
If two final target component have the same horizontal position, then the highest takes
precedence.
In the unlikely event that components have the exact same position, then an unique
internal component ID is automatically used, which guarantees a well-defined order but
which cannot be changed.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
262
5.15.2
Designing Mappings
Mapping Rules and Strategies
Priority Context node/item
When applying a function to different items in a schema or database, 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.
Priority-context is used 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.
A simplified version of the complete DB_CompletePO.mfd file available in the ...
\MapForceExamples folder, is shown below.
Note that there are multiple source components in this example. ShortPO is a Schema with an
associated XML instance file, while CustomersAndArticles is a database. The data from both are
then mapped to the CompletePO schema / XML file. The priority context icon is enclosed in a
circle as a visual indication.
Designating the a parameter of the equal function as the priority context would cause:
The CustomerNr in ShortPO is compared with the item Number in the database.
CustomerNr has been designated as the priority context, and is placed in the a
parameter of the equal function.
The CustomersAndArticles database is then searched (once) for the same number.
The b parameter contains the Number item from the database.
If the number is found, then the result is passed to the bool parameter of the filter
component (Customers).
The node/row parameter passes on the Customer 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.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Mapping Rules and Strategies
263
This means that the database is only searched once per CustomerNr supplied by
ShortPO.
Designating the b parameter of the equal function as the priority context would cause:
MapForce to search and load the first Number into the b parameter from the database
Check against the CustomerNr in the a parameter of ShortPO
If not equal, search through all CustomerNr of ShortPO
Search the database and load the next Number into b, check against a, and
Iterate through every Number in the database while trying to find that number in ShortPO.
This means that a database query is generated for each Number and the result is then
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
264
Designing Mappings
Mapping Rules and Strategies
compared to every CustomerNr of ShortPO.
Priority context and user-defined functions:
If a user-defined function has been defined of type "inline", the default setting, then a priority
context cannot be defined on one of the parameters of the user-defined function. The user-defined
function can, of course, contain other regular (non-inlined) user-defined functions which have
priority contexts set on their parameters.
5.15.3
Overriding the Mapping Context
In some mappings, in order to achieve the desired mapping output, it may be necessary to
override the mapping context. For this reason, some components provide an optional parentcontext item in their structure which enables you to influence the mapping context if so required.
Examples of such components are: aggregate functions, variables, and Join components.
An aggregate function with optional parent-context
To understand why the mapping context is important, let's add to the mapping an XML file that
contains nested nodes with multiple levels. On the Insert menu, click XML Schema/File, and
browse for the file: <Documents>\Altova\MapForce2017\MapForceExamples
\Altova_Hierarchical.xml.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Mapping Rules and Strategies
265
Altova_Hierarchical.xml
Importantly, in the XML file above, the Office parent node contains multiple Department nodes,
and each Department contains multiple Person nodes. If you open the actual XML file in an XML
editor, you can see that the distribution of people by office and department is as follows:
Office
Department
Number of people
Nanonull, Inc.
Administration
3
Marketing
2
Engineering
6
IT & Technical Support
4
Administration
2
Marketing
1
IT & Technical Support
3
Nanonull Partners, Inc.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
266
Designing Mappings
Mapping Rules and Strategies
Now let's assume that your mapping should count all people in all departments. To achieve this
requirement, you can add the count function from core | aggregate functions and map data as
follows:
If you preview the mapping at this stage, the output is 21, which corresponds to the total number
of people in all departments. Notice that the count function includes an optional parent-context
item, which so far has not been connected. As a result, the parent context of the count function
is the default root node of the source component (which, in this case, is the Altova item). This
means that all the persons, from all departments, are considered for the scope of the count
function. This is the way the mapping context works by default, as outlined in Mapping Rules and
Strategies, and this is sufficient in most mapping scenarios.
However, it is possible to override the default mapping context if necessary. To do this, add a
connection from the Department node to the parent-context item as shown below.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Designing Mappings
Mapping Rules and Strategies
267
By changing the mapping as shown above, you are instructing the mapping to iterate over people
records in the context of each office. Therefore, if you preview the mapping now, the output will
be 15*. This is exactly the number of people in the first office, "Nanonull, Inc.". The explanation is
that this time the people nodes were counted twice (once for each office). The count of people in
each office was 15 and 6, respectively. However, only the first result was returned (because the
function cannot return a sequence of values, only a simple value).
* Assuming that the target language of the mapping is other than XSLT 1.0.
You can further modify the mapping so as to change the mapping context to Department, as
shown below. This time the people records would be counted in the context of each department
(that is, 7 times, which corresponds to the total number of departments). Again, only the first of
the results is returned, so the mapping output is 3, which corresponds to the number of people in
the first department of the first office.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
268
Designing Mappings
Mapping Rules and Strategies
While this mapping is not doing much yet, its point is to illustrate how the parent-context item
influences the output of the mapping. Having this in mind, you can override the parent-context
in other mappings, such as those that contain variables or Join components. See also Example:
Grouping and Subgrouping Records.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Chapter 6
Debugging Mappings
270
Debugging Mappings
6
Debugging Mappings
MapForce includes a mapping debugger available for the MapForce BUILT-IN transformation
language. The mapping debugger helps you achieve the following goals:
View and analyze the values produced by the mapping at each individual connector level.
Highlight on the mapping the context (set of nodes) responsible for producing a particular
value.
Execute a mapping step-by-step, in order to see how MapForce processes or computes
each value in real time, and preview the mapping output as it is being generated.
Set milestones (breakpoints) at which the mapping execution should stop and display the
value(s) currently being processed.
View the history of values processed by a connector since mapping execution began up
until the current execution position.
The mapping debugger is available when the transformation language of the mapping is BUILT-IN.
If you start debugging a mapping designed for a different language, you will be prompted to
change the mapping language to BUILT-IN. You can also convert a mapping to BUILT-IN by
selecting the menu command Output | Built-in Execution Engine. In either case, the conversion
to BUILT-IN will be successful if the mapping does not include components that are not available
in the BUILT-IN language (for example, XSLT functions).
The MapForce debugger is unlike a traditional debugger in that it does not traverse your program
code line by line (since you do not write any code with MapForce). Instead, the debugger exposes
the results of MapForce-generated code produced from the mappings you design. More
specifically, the debugger logs values that are passed from and to mapping components through
their input and output connectors. The logged values are then available for your analysis directly
on the mapping or through dedicated windows.
The following sections highlight various ways in which you can use the mapping debugger.
Debug with breakpoints
When you need to stop the debugging execution at a particular place in the mapping, you
can set breakpoints, similar to how you would do that in a traditional development
environment. The difference is that breakpoints are added not to a line of code, but to an
input or output connector of a mapping component. You can also add conditions to
breakpoints (this can be useful if you want to stop the execution only if the set condition
is satisfied).
You can define breakpoints on the desired connectors and execute the mapping up to the
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Debugging Mappings
271
first encountered breakpoint, then go to the next one, and so on. This way you can
analyze the mapping context and values associated with chosen connectors. You can
also speed up or slow down the execution by means of the Step Into, Step Out, Step
Over, and Minimal Step commands provided by the debugger. These commands enable
you to skip portions of the mapping, or, on the contrary, execute portions of the mapping
in a more granular way if necessary.
Debug step-by-step
You can debug a mapping step-by-step, and analyze the mapping context and values
associated with each step. This scenario is similar to the previous one, in that you can
speed up or slow down execution using the Step Into, Step Out, Step Over, and
Minimal Step commands.
Analyze the log of values
You can configure MapForce to remember the log of all values (trace history) that were
processed by all connectors while you debug a mapping. Keeping the full trace history
may not be suitable for mappings that are data-intensive, so this option can be disabled if
necessary. When the option is enabled, you can analyze the full log of values processed
by each connector up until the current execution position. You can also instruct
MapForce to recreate the mapping context associated with any particular value, which
would help you understand why that value was produced.
Set the context to a value related to the current execution position
When the debugger is at a particular execution position on the mapping, it is possible to
analyze the context of a past value relative to the current execution position (this can be
compared to stepping slightly back in time):
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
272
Debugging Mappings
A context is meant to explain why a value is computed; in other words, it describes how
a particular value on the mapping came to be generated. The context is normally the
current execution position, although it can also be a context in the recent past that
MapForce enables you to set. When the context is set to a particular value, MapForce
highlights directly on the mapping the nodes that are relevant to it, provides tips next to
mapping connectors, and exposes additional information in debugger-related windows
(the Values, Context, and Breakpoints windows).
After you have inspected a mapping context that is not the same as the current execution
position, you can reset the context back to the current execution position:
Limitations
When MapForce executes a mapping, it may internally optimize code (for example, by
caching data, or by calculating intermediate results at arbitrary points). This may cause
certain connectors (and thus breakpoints) to be unreachable for debugging, in which case
MapForce displays a notification. Note that the MapForce code optimizations (and,
consequently, the behavior exposed by the debugger) may be different from one
MapForce release to the other, even though the mapping output is the same for a given
mapping.
The debugger can debug the output generation for one target component at a time. If
there are multiple target components on the mapping, you will need to select which one
should be executed by the debugger.
Currently, debugging is not supported for the database table actions (such as "Insert All",
"Update If", etc.) of database components.
Breakpoints cannot be added on any of the following entities: constants, the core |
position function, descendent items of "Copy-all" connections, parameters of "inline"
user-defined functions.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Debugging Mappings
6.1
Debugger Preparation
273
Debugger Preparation
Debugging preparation is primarily required for big data mappings that are likely to need a lot of
system memory to execute. This is the case of mappings that either process very big input or
output files, or repeatedly iterate through large collections of data.
To make debugging faster and reduce memory requirements, it is recommended to do the
following before you start debugging:
If the mapping is complex, remove or disconnect parts of the mapping that need not be
debugged.
If the mapping uses big input files, replace them with files of smaller size.
Ensure that the Keep full trace history option is disabled (see Debugger Settings )
Also, to ensure you are debugging the right output, check the following if applicable:
If the mapping has multiple target components, select the target component to be
debugged by clicking the Preview button (
).
If the mapping is a chained mapping (see Chained Mappings ), release the PassThrough (
) button on the intermediary component. Debugging Pass-Through
components is currently not supported.
Optionally, if you want the debugger to stop at some important connectors whose value you want
to analyze, add breakpoints to these connectors (see Adding and Removing Breakpoints ).
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
274
6.2
Debugging Mappings
Debugger Commands
Debugger Commands
You can access the debugger commands as follows:
In the Debug menu
As keyboard shortcuts
In the Debug toolbar.
Menu Command
Keyboard
Shortcut
Toolbar
button
Description
Debug | Start
debugging
F5
Starts or continues debugging until a
breakpoint is hit or the mapping finishes.
Debug | Stop
debugging
Shift + F5
Stops debugging. This command exits the
debug mode and switches MapForce back
to standard mode.
Debug | Step Into
F11
Executes the mapping until a single step is
finished anywhere in the mapping. In the
mapping debugger, a step is a logical
group of dependent computations which
normally produce a single item of a
sequence.
Depending on the mapping context, this
command roughly translates into "go to the
left/go to target child/go to source parent".
Debug | Step Over
F10
Continues execution until the current step
finishes (or finishes again for another item
of the sequence), or an unrelated step
finishes. This command steps over
computations that are inputs of the current
step.
Debug | Step Out
Shift + F11
Continues execution until the result of the
current step is consumed or a step is
executed that is not an input or child of the
consumption. This command steps out of
the current computation.
Depending on the mapping context, this
command roughly translates into "go to the
right/go to target parent/go to source child".
Debug | Minimal
Step
Ctrl + F11
Altova MapForce 2017 Professional Edition
Continues execution until a value is
produced or consumed. This command
subdivides a step and will typically stop
twice for each connection: once when its
source produces a value and once when its
target consumes it. MapForce does not
© 2017 Altova Gmb H
Debugging Mappings
Menu Command
Debugger Commands
Keyboard
Shortcut
Toolbar
button
275
Description
necessarily compute values in the order the
mapping would suggest, so production and
consumption events do not always follow
each other.
Deb ug toolb ar
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
276
6.3
Debugging Mappings
About the Debug Mode
About the Debug Mode
When you start debugging (by pressing F5, or F11, or Ctrl + F11), MapForce executes the
mapping in debug mode.
While MapForce is in debug mode, the mapping is read-only. Although you can move
components on the mapping area, most commands are not available. This includes
commands such as mapping validation and deployment, code generation,
documenting mappings, adding new components to the mapping area or reloading
existing ones, and others.
The debug mode enables you to analyze the context responsible for producing a particular value.
This information is available directly on the mapping, as well as in the Values, Context, and
Breakpoints windows. By default, these windows are displayed when you start debugging and are
hidden when you stop debugging.
MapForce is in debug mode (and the mapping is read-only) until you stop debugging, by pressing
Shift + F5 (or by clicking the Stop debugging
toolbar button).
The following image illustrates a sample mapping (SimpleTotal.mfd, from the <Documents>
\Altova\MapForce2017\MapForceExamples\ directory) that is debugged in steps (by pressing
F11 to advance a step).
The MapForce development environment in deb ug mode
The visual clues and other information provided by MapForce while in debug mode are described
below.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Debugging Mappings
About the Debug Mode
277
The mapping pane
While debugging, the mapping pane displays additional information:
o Data overlays (see below) show the current value and related values near their
connectors.
o The current context (shown as a structure in the Context window) is highlighted as
follows:
Connectors in the context are striped magenta (
).
Connectors in ambiguous context are dotted magenta (
).
Connections in the context are striped magenta.
Connections in ambiguous context are striped magenta but lighter.
o The current execution location is displayed with a green connector icon (
).
Data overlays
The values processed by each connector are displayed as data overlays (small
rectangles) near their corresponding connector. A currently selected data overlay is
displayed with thick red border. Values changed from the last step are displayed in dark
red. For nodes with simple content, the data overlay combines two values - the node
name and the value. If the node name has been iterated multiple times before the current
execution position, the index of the current iteration is indicated by the number in square
brackets.
Data overlays have the following behavior:
o Pointing the mouse to a data overlay brings it temporarily to the foreground, clicking it
does it permanently. Clicking also selects the corresponding connector.
o Data overlays can be moved by dragging.
o Data overlays move when a component is moved. Therefore, if the data overlays appear
stacked because the components are too close to each other, drag the components
around the mapping area to make more space, and the data overlays will move together
with the component.
o Clicking a data overlay shows its value in the Values window.
o Clicking a connector also selects its data overlay.
Breakpoints
Breakpoints are designated milestones at which the mapping should break during
execution in debug mode. This term may be already familiar to you by analogy with other
integrated development environments. Unlike other development environments where you
add breakpoints to a line of code, a breakpoint in MapForce can be added to an input or
output connector (small triangle to the left or right of the connection). On the mapping
pane, breakpoints are represented as red circles. Any defined breakpoints are also
displayed in the Breakpoints window. See also Adding and Removing Breakpoints.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
278
Debugging Mappings
About the Debug Mode
Current debugger position
The green triangle (
) indicates the position of the debugger. This position is either an
input or an output connector of any given component.
The value currently being processed is also displayed in the Values window, on the
Context tab.
The set of connections and/or connectors colored in striped magenta indicate the current
mapping context. The same information is also displayed as a hierarchical structure in
the Context window (see Using the Context Window ).
When you set manually the context of a value, the current debugger position is in a
position in the past relative to the most current execution position. To help you
distinguish between the most current execution position and the one in the past, the
"current position" connector may appear with the following colors in the debugger
interface.
Green is "the present"; it indicates the current execution position (see Viewing the
Current Value of a Connector).
Yellow is "the past"; it indicates that you are looking at some connector in the
past, relative to the current execution position. This may happen after you set a
context manually (see Setting the Context to a Value).
Values window
The Values window provides information about the values processed by the mapping. It
enables you to see what the mapping processes at the current execution position, or in a
particular context that you can set yourself. See also Using the Values Window.
Context window
The Context window provides a hierarchical view of the set of nodes and functions that are
relevant for the current debugger position. See also Using the Context Window.
Breakpoints window
The Breakpoints window displays the list of debugging breakpoints created since
MapForce was started. If you have defined breakpoints on multiple mappings, all of them
appear in the Breakpoints window. See also Using the Breakpoints Window.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Debugging Mappings
6.4
Adding and Removing Breakpoints
279
Adding and Removing Breakpoints
Breakpoints are designated milestones at which the mapping should break during execution in
debug mode. Any breakpoints you create are stored globally for all mappings and are displayed in
the Breakpoints window. Breakpoints are valid until you either explicitly delete them, or close
MapForce.
Note:
Breakpoints cannot be added on any of the following entities: constants, the core |
position function, descendent items of "Copy-all" connections, parameters of "inline"
user-defined functions.
Breakpoints can be simple or conditional. Simple breakpoints stop the mapping execution
unconditionally. Conditional breakpoints stop the mapping execution only when the condition
assigned to them is satisfied. Conditions take the form of MapForce built-in library functions to
which you supply custom values. In other words, if the condition returns true, the breakpoint will
stop the mapping execution.
To create a simple breakpoint, do one of the following:
Right-click an input or output connector (the small triangles to the left or right of a
component), and select Debugger Breakpoint.
Click an input or output connector, and then press F9.
To create a conditional breakpoint:
1.
Right-click a connector, and select Breakpoint properties.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
280
Debugging Mappings
2.
3.
Adding and Removing Breakpoints
Click to select both the Breakpoint and Condition check boxes.
Select the required function from the list, and enter the function value (if applicable). For
example, in the example above, the breakpoint will stop the mapping execution if the
value passing through it is greater than 2.
If the data type of the connector where you add the conditional breakpoint does not
match the type(s) expected by the function, MapForce will attempt to convert the
data type automatically. If automatic conversion is not possible, mapping execution
will fail. To avoid this, make sure to use compatible data types. For example, the
function core.starts-with expects a string value, so the breakpoint's connector
must have the same type.
Removing breakpoints
To remove a breakpoint, right-click the connector on which the breakpoint exists, and select
Debugger Breakpoint. Alternatively, click the input or output connector on which the breakpoint
exists, and then press F9.
You can also remove breakpoints from the Breakpoints window (see Using the Breakpoints
Window ).
Unreachable breakpoints
There may be cases when MapForce displays a "Breakpoints cannot be reached" message:
This indicates that breakpoints cannot be reached by the debugger, because of one of the
following reasons:
A breakpoint has been defined on a connector that does not take part in the mapping.
The breakpoint cannot be reached by MapForce because of execution optimizations (see
Limitations).
Click Continue to advance to the next defined breakpoint (or go to the end of debugging
execution). Click Step to start debugging in steps.
You can disable notifications about unreachable breakpoint encountered by the debugger, either
by clicking Don't show this message again, or as follows:
1.
2.
On the Tools menu, click Options.
Click Messages.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Debugging Mappings
3.
Adding and Removing Breakpoints
281
Click to clear the Inform about unreachable breakpoints check box.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
282
6.5
Debugging Mappings
Using the Values Window
Using the Values Window
The Values window displays information about the values processed by the mapping when in
debug mode. The information displayed in the Values window depends on the current debugger
position, and on the user interface elements that you clicked. The Values window contains the
following tabs:
The "Context" tab
The Context tab displays the value currently being processed (the same value whose
context is shown in the Context window). This is either the value at the current execution
position of the debugger, or the value of a connector processed in the past. MapForce
helps you distinguish between the two using colors:
Green is "the present"; it indicates the current execution position (see Viewing the
Current Value of a Connector).
Yellow is "the past"; it indicates that you are looking at some connector in the
past, relative to the current execution position. This may happen after you set a
context manually (see Setting the Context to a Value).
The "Related" tab
The Related tab displays values that are related to (or represent the "near past" of) the
currently processed value. Normally, you do need to explicitly click this tab; MapForce
switches to it automatically when you click the data overlay of a connector that is related
to the current execution position of the debugger. See Stepping back into Recent Past.
The "Sequence" tab
When present, the Sequence tab enables you to get access to the values of a connector
that processes a sequence. This tab is visible only when a connector has processed a
sequence of items (for example, an aggregate function such as sum or count does that).
When you click the data overlay of a connector that processed a sequence of items, the
Values window displays an entry in the format "n items", where n is the number of items
processed by the connector. To get access to each value, double-click this entry (or
right-click it, and select Expand Sequence from the context menu).
The values are then displayed in the Sequence tab.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Debugging Mappings
Using the Values Window
283
The "History" tab
The History tab displays values have been processed by a particular node since
debugging started and up to the current execution position. See Viewing the History of
Values Processed by a Connector.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
284
6.6
Debugging Mappings
Using the Context Window
Using the Context Window
While MapForce is in debug mode, the Context window displays a structure of connectors that
are relevant to the current position of the debugger. In other words, it provides the mapping
context responsible for producing the current mapping value.
MapForce builds the current context as follows:
1.
2.
3.
Start with the root node of the target structure.
Descend to the current target node.
From the current target node, move left inside the mapping through any components that
lead to the current position. These components may be filter or sort components, built-in
or user-defined functions, variables, and so on.
The Context window serves both as informational and as a navigational aid. To select a particular
node in the mapping directly from the current context, right-click the node in the Context window,
and click Select in mapping. This might be especially useful when the mapping is large, so as
to avoid extensive scrolling.
The Context window may display the following special icons and notation:
Icon
Description
Represents the mapping to which the context belongs. This can be either the
main mapping or the mapping of a user-defined function.
Represents a connector. The target nodes processed so far have their position
displayed in square brackets.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Debugging Mappings
Icon
Using the Context Window
285
Description
Represents the current connector (the most recent execution position). This is
the source of the current value in the Values window.
In some rare situations, it is possible that a computed value is used for
multiple connectors. In this case, multiple green icons may appear.
Represents the current connector when the debugger is at some position in
the past relative to the most recent execution post. This may happen after you
set the context to a value (see Setting the Context to a Value ).
In addition to the icons above, the Context window includes the standard icons of any component
types that are present in the mapping.
Context window and user-defined functions
If the current context includes any user-defined functions, they are displayed in the Context
window as well. Note that if the current context is for computing an input value of a user-defined
function, the context is determined as follows:
1.
2.
Note:
From the target to the output connector of the user-defined function to the input connector
of the user-defined function
From there further to the left.
A user-defined function may occur multiple times in the context. This happens either
because several function calls are chained or because the user-defined function is defined
as recursive.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
286
6.7
Debugging Mappings
Using the Breakpoints Window
Using the Breakpoints Window
The Breakpoints window enables you to view and manage breakpoints globally. By default, the
Breakpoints window is displayed when MapForce is in debug mode. To make the Breakpoints
window visible at all times, select the menu command View | Debug Windows | Breakpoints.
The Breakpoints window displays all breakpoints created since you started MapForce, grouped by
the mapping file to which they belong. While MapForce is open, any breakpoints associated with
any mapping are "remembered" by MapForce and displayed in the Breakpoints window, even if
you closed the mapping file in the meanwhile. The mapping that is currently being debugged is
represented with standard text color in the Breakpoints window, while other mappings (the ones
that are closed or not active) are grayed out.
You can quickly open any mapping by double-clicking it (or any of its breakpoints) in the
Breakpoints window.
Note:
Once you close or restart MapForce, all breakpoints are removed.
Information about breakpoints is displayed as a grid with the following columns:
Column
Description
Name
The name of the node where the breakpoint belongs.
Parent
The name of the mapping component where the breakpoint belongs.
Trace
value
The value that passes through the connector on which the breakpoint is.
The trace value is displayed during debugging execution.
Condition
If the breakpoint is conditional, this column displays the condition of the
breakpoint.
Breakpoints may be associated with any of the following icons.
Icon
Description
Active breakpoint. Denotes a breakpoint from the mapping that is currently
being debugged.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Debugging Mappings
Icon
Using the Breakpoints Window
287
Description
Inactive breakpoint. Denotes a breakpoint from a mapping that is open, but is
not currently being debugged.
Inaccessible breakpoint. Denotes a breakpoint that cannot be reached by the
debugger.
Conditional breakpoint. Denotes a breakpoint with a condition attached to it.
To view or change the properties of a breakpoint:
Right-click it, and select Breakpoint Properties from the context menu.
To delete a breakpoint:
Right-click the breakpoint you want to delete, and then select Delete Breakpoint from
the context menu.
Click a breakpoint, and then press Delete.
The context command Delete All Breakpoints removes all breakpoints displayed in the
Breakpoints window, regardless of the mapping where they belong.
See also: Adding and Removing Breakpoints
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
288
6.8
Debugging Mappings
Previewing Partially Generated Output
Previewing Partially Generated Output
When you are debugging in steps or using breakpoints, you can view the mapping output
generated up to the current debugger position. Previewing partially generated output is supported
by XML, flat text, and EDI target components.
By default, when you press F5 (without having defined any breakpoints), MapForce executes the
entire mapping in debug mode, and then switches to the Output tab, displaying the final
generated output. However, if you have defined breakpoints, or if you are debugging in steps (F11,
or Ctrl + F11), the debugger execution stops while the mapping output is still being generated.
Even if the mapping output is partially written at this stage, you can still click to the Output tab,
and preview it.
Limitations
The currently computed target node is not always displayed in the Output tab. For
example, XML attributes are collected internally and written at once.
If the output produces multiple files, only the currently written file can be displayed;
switching to another output file is disabled.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Debugging Mappings
6.9
Viewing the Current Value of a Connector
289
Viewing the Current Value of a Connector
When the current execution position of the debugger (
) is on a particular connector (either
because you are debugging in steps, or because there is a breakpoint defined on the connector),
the current value processed by the connector is displayed in the Context tab of the Values
window. This is the value that is about to be written to the output, that is, "the present". It is also
the value whose context is displayed in the Context window (see Using the Context Window ).
To understand this case, open the PreserveFormatting.mfd sample from the <Documents>
\Altova\MapForce2017\MapForceExamples\ directory. Click the input connector of the Number
node on the target component, and press F9 to add a breakpoint on it.
Then press F5 to start debugging and observe the results.
As shown in the image, the current debugger position
(and the breakpoint
) is on the
Number node of the target component. The Values window indicates that this node processes the
value "1" (this value is also highlighted with a thick red border on the mapping).
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
290
Debugging Mappings
Stepping back into Recent Past
6.10 Stepping back into Recent Past
When you click a data overlay (small rectangular box) next to a mapping connector, the Values
window displays the name and, optionally, the value associated with the selected connector. The
focus now is no longer on the current debugger position, but on the selected data overlay. You
can consider this view as stepping slightly back in the debugging history. This is the "near" past,
since the mapping displays data overlays only for the last few connectors related to the current
debugger position. When you click such a "related" data overlay, the Values window switches
automatically to the Related tab.
For an illustration of this scenario, open the mapping PreserveFormatting.mfd from the
<Documents>\Altova\MapForce2017\MapForceExamples\ directory.
After opening the mapping, click the connector next to the Number node on the target component,
and press F9 to add a breakpoint on it. Press F5 to start debugging, and then click the data
overlay (small rectangular box) next to the Number node of the source component.
Because a connector is typically iterated multiple times for the lifetime of a mapping, the current
index of the iteration is displayed enclosed with square brackets: <Number>[1]. Also, because
the connector carries a value, its value is also represented after the equal sign: <Number>[1]=1.
The same value is displayed on a new row in the Values window, as shown below.
If you need additional information about a particular value, remember that you can recreate the
context that produced it (see Setting the Context to a Value ).
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Debugging Mappings
Viewing the History of Values Processed by a Connector
291
6.11 Viewing the History of Values Processed by a Connector
If the option Keep full trace history is enabled (see Debugger Settings ), you can view the
history of all values that were processed by that connector (up to the current execution position).
The history is displayed when you click a connector, and then click the History tab of the Values
window. Note that this operation is meaningful only for connectors that have processed values
since the beginning of mapping execution until the current debugger position.
To illustrate this case, let's debug a mapping from begging till end without using any breakpoints,
and then watch the history of all values that were processed by a particular connector. First, open
the mapping PreserveFormatting.mfd from the <Documents>\Altova\MapForce2017
\MapForceExamples\ directory. If it is already open, make sure to do the following:
Clear any breakpoints, if such exist (see Adding and Removing Breakpoints )
Stop debugging if it is currently in progress, by pressing Shift + F5.
When ready, press F5 start a new debugging operation. When you press F5, MapForce executes
the mapping in debug mode, and switches to the Output tab. Click the Mapping tab to go back
to the main mapping window, and then click the result node of the format-number function
(highlighted in red in the image below). Finally, click the History tab of the Values window, and
notice the displayed values.
As shown in the image above, this particular node (result) has processed four values in total. If
you need additional information about a particular value, remember that you can recreate the
context that produced it (see Setting the Context to a Value ).
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
292
Debugging Mappings
Setting the Context to a Value
6.12 Setting the Context to a Value
Setting the context to a value is an action that can be compared to stepping into the past, in order
to view more details about the mapping context that produced that value. You can set the context
to any value displayed in the Values window (in the Related tab, Sequence tab, or History tab).
If you have enabled the Keep full trace history option (see Debugger Settings ), the History tab
displays all values processed by the currently selected connector; therefore, in this case, you can
additionally set the context to any value in the past for that connector.
To set the context to a value, do one of the following:
Right-click the value, and select Set Context from the context menu.
Double-click the value.
When you set the context to a value, MapForce highlights the mapping area so as to recreate the
situation that produced that value, and populates the Values window and the Context window
according to the selected context. For a legend to visual clues used on the mapping area while in
a context, see About the Debug Mode. For information about the context itself, see Using the
Context Window.
The connector of a manually-set context is yellow (
), which indicates that you are no longer at
the most recent execution position. To switch back to the most recent execution position (when
applicable), click the Reset to Current button on the Context tab of the Values window.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Debugging Mappings
Debugger Settings
293
6.13 Debugger Settings
To access the settings applicable to the MapForce debugger, select the menu command Tools |
Options, and then click Debugger. The available settings are as follows:
Maximum storage length of values
Defines the string length of values displayed in the Values window (at least 15
characters). Note that setting the storage length to a high value may deplete available
system memory.
Keep full trace history
Instructs MapForce to keep the history of all values processed by all connectors of all
components in the mapping for the duration of debugging. If this option is enabled, all
values processed by MapForce since the beginning of debug execution will be stored in
memory and available for your analysis in the Values window, until you stop debugging. It
is not recommended to enable this option if you are debugging data-intensive mappings,
since it may slow down debugging execution and deplete available system memory. If
this option is disabled, MapForce keeps only the most recent trace history for nodes
related to the current execution position.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
Chapter 7
Data Sources and Targets
296
Data Sources and Targets
7
Data Sources and Targets
This section describes the various source and target component types that MapForce can map
from/to.
XML and XML schema
Databases and MapForce
Mapping CSV and Text files
HL7 v3.x to/from XML schema
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
7.1
XML and XML schema
297
XML and XML schema
In the introductory part of this documentation, you have seen examples of simple mappings that
use XML and XML schema files as source or target components. This section provides further
information about using XML components in your mappings. It includes the following topics:
XML Component Settings
Using DTDs as "schema" components
Derived XML Schema types - mapping to
QName support
Nil Values / Nillable
Comments and Processing Instructions
CData sections
Wildcards - xs:any
7.1.1
Generating an XML Schema
MapForce can automatically generate an XML schema based on an existing XML file if the XML
Schema is not available. When you add to the mapping area an XML file without a schema, the
following dialog box appears.
When MapForce generates a schema from an XML file, data types for elements/attributes must
be inferred from the XML instance document and may not be exactly what you expect. It is
recommended that you check whether the generated schema is an accurate representation of the
instance data.
7.1.2
XML Component Settings
After you add an XML component to the mapping area, you can configure the settings applicable
to it from the Component Settings dialog box. You can open the Component settings dialog box in
one of the following ways:
Select the component on the mapping, and, on the Component menu, click Properties.
Double-click the component header.
Right-click the component header, and then click Properties.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
298
Data Sources and Targets
XML and XML schema
XML Component Settings dialog b ox
The available settings are as follows.
Component name
Altova MapForce 2017 Professional Edition
The component name is automatically generated when you
© 2017 Altova Gmb H
Data Sources and Targets
XML and XML schema
299
create the component. You can however change the name at
any time.
If the component name was automatically generated and you
select an instance file after that, MapForce will prompt you to
optionally update the component name as well.
The component name can contain spaces (for example,
"Source XML File") and full stop characters (for example,
"Orders.EDI"). The component name may not contain
slashes, backslashes, colons, double quotes, leading or
trailing spaces. In general, be aware of the following
implications when changing the name of the component:
If you intend to deploy the mapping to FlowForce
Server, the component name must be unique.
It is recommended to use only characters that can
be entered at the command line. National characters
may have different encodings in Windows and at the
command line.
Schema file
Specifies the name or path of the XML schema file used by
MapForce to validate and map data.
To change the schema file, click Browse and select the new
file. To edit the file in XMLSpy, click Edit.
Input XML file
Specifies the XML instance file from which MapForce will
read data. This field is meaningful for a source component
and is filled when you first create the component and assign
to it an XML instance file.
In a source component, the instance file name is also used
to detect the XML root element and the referenced schema,
and to validate against the selected schema.
To change the location of the file, click Browse and select
the new file. To edit the file in XMLSpy, click Edit.
Output XML file
Specifies the XML instance file to which MapForce will write
data. This field is meaningful for a target component.
To change the location of the file, click Browse and select
the new file. To edit the file in XMLSpy, click Edit.
Prefix for target namespace
Allows you to enter a prefix for the target namespace. Ensure
that the target namespace is defined in the target schema,
before assigning the prefix.
Add schema/DTD reference
Adds the path of the referenced XML Schema file to the root
element of the XML output. The path of the schema entered
in this field is written into the generated target instance files
in the xsi:schemaLocation attribute, or into the DOCTYPE
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
300
Data Sources and Targets
XML and XML schema
declaration if a DTD is used.
Note that, if you generate code in XQuery or C++, adding the
DTD reference is not supported.
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 (for
example, if you want to send the resulting XML output to
someone who does not have access to the underlying XML
Schema).
Write XML declaration
This option enables you to suppress the XML declaration
from the generated output. By default, the option is enabled,
meaning that the XML declaration is written to the output.
This feature is supported as follows in MapForce target
languages and execution engines.
Target language
/ Execution
engine
When output is
a file
When output is
a string
Built-in
Yes
Yes
MapForce Server
Yes
Yes
XSLT, XQuery
Yes
No
Code generator (C Yes
++, C#, Java)
Cast values to target types
Yes
Allows you to define if the target XML schema types should
be used when mapping, or if all data mapped to the target
component should be treated as string values. By default,
this setting is enabled.
Deactivating this option allows you to retain the precise
formatting of values. For example, 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.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
XML and XML schema
301
Note that disabling this option will also disable the detection
of invalid values, e.g. writing letters into numeric fields.
Pretty print output
Reformats the output XML document to give it a structured
look. Each child node is offset from its parent by a single tab
character.
Output Encoding
Allows you specify the following settings of the output
instance file:
Encoding name
Byte order
Whether the byte order mark (BOM) character
should be included.
By default, any new components have the encoding defined
in the Default encoding for new components option. You
can access this option from Tools | Options, General tab.
If the mapping generates XSLT 1.0/2.0, activating the Byte
Order Mark check box does not have any effect, as these
languages do not support Byte Order Marks.
StyleVision Power Stylesheet
file
This option allows you to select or create an Altova
StyleVision stylesheet file. Such files enable you to output
data from the XML instance file to a variety of formats suitable
for reporting, such as HTML, RTF, and others.
See also Using Relative Paths on a Component.
Enable input processing
optimizations based on min/
maxOccurs
This option allows special handling for sequences that are
known to contain exactly one item, such as 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, disable this check box.
Save all file paths relative to
MFD file
7.1.3
When this option is enabled, MapForce saves the file paths
displayed on the Component Settings dialog box relative to
the location of the MapForce Design (.mfd) file. See also
Using Relative Paths on a Component.
Using DTDs as "Schema" Components
Starting with MapForce 2006 SP2, namespace-aware DTDs are supported for source and target
components. The namespace-URIs are extracted from the DTD "xmlns"-attribute declarations, to
make mappings possible.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
302
Data Sources and Targets
XML and XML schema
However, some DTDs contain xmlns*-attribute declarations without namespace-URIs (for
example, DTDs used by StyleVision ). Such DTDs have to be extended to make them useable in
MapForce. Specifically, you can make such DTDs useable 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'
...
>
7.1.4
Derived XML Schema Types
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 a derived type called US-Address, in XMLSpy. The
base type (or originating complex type) is AddressType. Two extra elements were added to
create the derived type US-Address: Zip and State.
Sample derived type (XMLSpy schema view)
The following example shows you how to map data to or from derived XML schema types.
1.
2.
On the Insert menu, click XML Schema/File, and open the following XML Schema:
<Documents>\Altova\MapForce2017\MapForceExamples\Tutorial
\MFCompany.xsd.
When prompted to supply an instance file, click Skip, and then select Company as the
root element.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
XML and XML schema
3.
Click the
button next to the Address element. This button indicates that derived
types exist for this element in the schema.
4.
Select the check box next to the derived type you want to use (US-Address, in this
case), and confirm with OK. A new element Address xsi:type="US-Address" has been
added to the component.
© 2017 Altova Gmb H
303
Altova MapForce 2017 Professional Edition
304
Data Sources and Targets
XML and XML schema
You can now map data to or from the US-Address derived type.
Note that you can also include multiple derived types by selecting them in the Derived Types
dialog box. In this case, each would have its own xsi:type element in the component.
7.1.5
QNames
MapForce resolves QName (qualified name) prefixes (http://www.w3.org/TR/xml-names/#nsqualnames) when reading data from XML files at mapping execution run-time.
QNames are used to reference and abbreviate namespace URIs in XML instance documents.
There are two types of QNames: Prefixed and Unprefixed QNames.
PrefixedName
Prefix ':' LocalPart
UnPrefixedName
LocalPart
where LocalPart is an Element or Attribute name.
For example, in the listing below, <x:p/> is a QName, where:
the prefix "x" is an abbreviation of the namespace "http://myCompany.com".
p is the local part.
<?xml version='1.0'?>
<doc xmlns:x="http://myCompany.com">
<x:p/>
</doc>
MapForce also includes several QName-related functions in the core | QName functions
library.
7.1.6
Nil Values / Nillable
The XML Schema specification allows for an element to be valid without content if the
nillable="true" attribute has been defined for that specific element in the schema. In the
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
XML and XML schema
305
instance XML document, you can then indicate that the value of an element is nil by adding the
xsi:nil="true" attribute to it. This section describes how MapForce handles nil elements in
source and target components.
'xsi:nil' versus 'nillable'
The xsi:nil="true" attribute is defined in the XML instance document.
The xsi:nil="true" attribute indicates that, although the element exists, it has no content. Note
that the xsi:nil="true" attribute applies to element values, and not to attribute values. An
element with xsi:nil="true" may still have other attributes, even if it does not have content.
The xsi:nil attribute is not displayed explicitly in the MapForce graphical mapping, because it is
handled automatically in most cases. Specifically, a "nilled" node (one that has the
xsi:nil="true" attribute) exists, but its content does not exist.
The nillable="true" attribute is defined in the XML schema. In MapForce, it can be present in
both the source and target components.
Nillable elements as mapping source
MapForce checks the xsi:nil attribute automatically, whenever a mapping reads data from nilled
XML elements. If the value of xsi:nil is true, the content will be treated as non-existent.
When you create a Target-driven mapping from a nillable source element to a nillable target
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
306
Data Sources and Targets
XML and XML schema
element with simple content (a single value with optional attributes, but without child elements),
where xsi:nil is set on a source element, MapForce adds the xsi:nil attribute to the target
element (for example, <OrderID xsi:nil="true"/>).
When you create a Copy-All mapping from a nillable source element to a nillable target element,
where xsi:nil is set on a source element, MapForce adds the xsi:nil attribute to the target
element (for example, <OrderID xsi:nil="true"/>).
To check explicitly whether a source element has the xsi:nil attribute set to true, use the isxsi-nil function. It returns TRUE for nilled elements and FALSE for other nodes.
To substitute a nilled (non-existing) source element value with something specific, use the
substitute-missing function.
Notes:
Connecting the exists function to a nilled source element returns TRUE, since the
element node actually exists, even if it has no content.
Using functions that expect simple values (such as multiply and concat) on
elements where xsi:nil has been set does 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.
Nillable elements as mapping target
When you create 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, MapForce inserts the xsi:nil attribute
into the target element (for example, <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. For such cases, 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.
To force the creation of an empty target element with xsi:nil set to true, connect the set-xsinil function directly to the target element. This works for target elements with simple and
complex types.
If the node has simple type, 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 (for example, multiply) involved a nilled source
node and therefore yielded no result.
Note:
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
XML and XML schema
307
Functions which generate xsi:nil cannot be passed through functions or
components which only operate on values (such as the if-else function).
Mapping NULL database fields to xsi:nil
If you map a NULL database field to an nillable element of an XML schema, MapForce generates
only those target elements which actually contain database data. Elements of NULL database
fields are not created in the target component. Connecting the exists node function to such a
source element results in false for the NULL fields.
To force the creation of all elements in the target component, use the substitute-missingwith-xsi-nil function from the node functions of the core library.
The screenshot above illustrates how the substitute-missing-with-xsi-nil function is used
to create target elements for all database fields:
All missing/NULL database fields contain <OrderID xsi:nil="true"/> in the target element.
Existing data from database fields is mapped directly to the target element e.g.
<OrderID>1</OrderID>.
To see the NULL fields of a database component, click the Database Query button and run a
query on the database table(s). Null fields are shown as [NULL] in the Results window.
Mapping xsi:nil to NULL database fields
If you map a nilled XML element to a database column, MapForce writes a NULL value to the
database. You can also use the set-null function if you want to set a database field to NULL
unconditionally.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
308
7.1.7
Data Sources and Targets
XML and XML schema
Comments and Processing Instructions
Comments and Processing Instructions can be inserted into target XML components. Processing
instructions are used to pass information to applications that further process XML documents.
Note that Comments and Processing instructions cannot be defined for nodes that are part of a
copy-all mapped group.
To insert a Processing Instruction:
1.
2.
3.
Right-click an element in the target component and select Comment/Processing
Instruction, then one of the Processing Instruction options from the menu (Before, After)
Enter the Processing Instruction (target) name in the dialog and press OK to confirm, e.g.
xml-stylesheet.
This adds a node of this name to the component tree.
You can use, for example, a constant component to supply the value of the Processing
Instruction attribute, e.g. href="book.css" type="text/css".
Note:
Multiple Processing Instructions can be added before or after any element in the target
component.
To insert a comment:
1.
2.
Right-click an element in the target component and select Comment/Processing
Instruction, then one of the Comment options from the menu (Before, After).
This adds the comment node ( <!--comment() ) to the component tree.
Use a constant component to supply the comment text, or connect a source node to the
comment node.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
XML and XML schema
309
Note:
Only one comment can be added before and after a single target node. To create multiple
comments, use the duplicate input function.
To delete a Comment/Processing Instruction:
Right-click the respective node, select Comment/Processing Instruction, then select
Delete Comment/Processing Instruction from the flyout menu.
7.1.8
CDATA Sections
CDATA sections are used to escape blocks of text containing characters which would normally
be interpreted as markup. CDATA sections start with "<![CDATA[" and end with the "]]>".
Target nodes can now write the input data that they receive as CDATA sections. The target node
components can be:
XML data
XML data embedded in database fields
XML child elements of typed dimensions in an XBRL target
To create a CDATA section:
1.
Right-click the target node that you want to define as the CDATA section and select
"Write Content as CDATA section".
A prompt appears warning you that the input data should not contain the CDATA section
close delimiter ']]>', click OK to close the prompt.
The [C.. icon shown below the element tag shows that this node is now defined as a
CDATA section.
Note:
CDATA sections can also be defined on duplicate nodes, and xsi:type nodes.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
310
Data Sources and Targets
XML and XML schema
Example:
The HTMLinCDATA.mfd mapping file available in the ...\MapForceExamples folder shows an
example of where CDATA sections can be very useful.
In this example:
Bold start (<b>) and end (</b>) tags are added to the content of the Trademark source
element.
Italic start (<i>) and end (</i>) tags are added to the content of the Keyword source
element.
The resulting data is passed on to duplicate text() nodes in the order that they appear in
the source document, due to the fact the Subsection element connector, has been
defined as a Source Driven (Mixed content) node.
The output of the MixedContent node is then passed on to the Description node in the
ShortInfo target component, which has been defined as a CDATA section.
Clicking the Output button shows the CDATA section containing the marked-up text.
7.1.9
Wildcards - xs:any / xs:anyAttribute
The wildcards xs:any (and xs:anyAttribute) allow you to use any elements/attributes from
schemas. The screenshot shows the "any" element in the Schema view of XMLSpy.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
In MapForce, a Change Selection (
xs:anyAttribute).
XML and XML schema
311
) button appears to the right of the xs:any element (or
When clicked, the Change Selection button
opens the "Wildcard selections" dialog box. The
entries in this list show the global elements and attributes declared in the current schema.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
312
Data Sources and Targets
XML and XML schema
Clicking one or more of the check boxes and confirming with OK, inserts that element/attribute
(and any other child nodes) into the component. The wildcard elements or attributes are inserted
immediately after the node whose Change Selection (
) button was clicked.
You can now map to/from these nodes as with any other element.
On a component, the wildcard elements or attributes can be recognized by the (xs:any) text
appended to their name.
To remove a wildcard element, click the Change Selection (
the "Wildcard selections" dialog box.
) button, and then deselect it from
Wildcards and dynamic node names
Mapping data to or from wildcards is generally suitable where all possible elements or attributes
that appear in the XML instance are declared by the component's XML schema (or can be
imported from external schemas). However, there may be situations where elements or attributes
appearing in an instance are too many to be declared in the schema. Consider the following
instance where the number of child elements of <message> is arbitrary:
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
XML and XML schema
313
<?xml version="1.0" encoding="UTF-8"?>
<message>
<line1>1</line1>
<line2>2</line2>
<line3>3</line3>
................
<line999></line999>
</message>
For such situations, use dynamic access to node names (see Mapping Node Names) instead of
wildcards.
Adding elements from a different schema as wildcards
Elements from a schema other than the one assigned to the component can also be used as
wildcards. To make such elements visible on the component, click the Import a different
schema button on the "Wildcard selections" dialog box. This opens a new dialog box where you
have two options:
1.
2.
Import schema
Generate wrapper schema
For example, the image below illustrates what happens if you attempt to import an external
schema called HasExpenses.xsd into a current schema assigned to a component.
The Import schema option imports the external schema into the current schema assigned to the
component. Be aware that this option overrides the existing schema of the component on the
disk. If the current schema is a remote schema that was opened from a URL (see Adding
Components from a URL) and not from the disk, it cannot be modified. In this case, use the
Generate wrapper schema option.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
314
Data Sources and Targets
XML and XML schema
The Generate wrapper schema option creates a new schema file called a "wrapper" schema.
The advantage of using this option is that the existing schema of the component is not modified.
Instead, a new schema will be created (that is, the wrapper schema) which will include both the
existing schema and the schema to be imported. When you select this option, you are prompted
to choose where the wrapper schema should be saved. By default, the wrapper schema has a
name in the form somefile-wrapper.xsd. After you save the wrapper schema, it is by default
automatically assigned to the component, and a dialog box prompts you:
Click Yes to revert to the previous schema; otherwise click No to keep the newly created wrapper
schema assigned to the component.
7.1.10
Merging Data from Multiple Schemas
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 Processing Multiple Input or
Output Files Dynamically.
The CompletePO.mfd file available in the ...\MapForceExamples folder shows how three XML
files are merged into one purchasing order XML file.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
XML and XML schema
315
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. (There is only one customer
in this file with the Customer number of 3)
Customers is a schema with an associated XML instance file and contains customer
number and customer information details, i.e. Name and Address info.
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 generated by
MapForce (although it would be possible to create if you had a CompletePO.xml instance file).
The structure of CompletePO is a combination of the source XML file structures.
The filter component (Customer) is used to find/filter 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
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
316
Data Sources and Targets
XML and XML schema
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 "ontrue" 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.
7.1.11
Declaring Custom Namespaces
By default, when a mapping produces XML output, the namespace (or set of namespaces) of
each element and attribute is automatically derived by MapForce from the schema associated
with the target component. This is the default behavior in MapForce and is suitable for most
mapping scenarios that involve generation of XML output.
However, there might be cases when you want to have more control over namespaces of elements
in the resulting XML output. For example, you may want to manually declare the namespace of an
element directly from the mapping.
To understand how this works, open the BooksToLibrary.mfd mapping available in the
<Documents>\Altova\MapForce2017\MapForceExamples\Tutorial\. Right-click the library
node, and select Add Namespace from the context menu.
Notice that two new nodes are now available under the library node: a namespace and a
prefix.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
XML and XML schema
317
You can now map to them string values from the mapping. In the image below, two constants
were defined (from Insert | Constant menu command) that provide the namespace "altova.library"
and the prefix "lib":
The result is that, in the generated output, an xmlns:<prefix>="<namespace>" attribute is added
to the element, where <prefix> and <namespace> are values that come from the mapping (in this
case, from constants). The generated output will now look as follows (notice the highlighted part):
<?xml version="1.0" encoding="UTF-8"?>
<library xmlns:lib="altova.library" xmlns:xsi="http://www.w3.org/2001/
XMLSchema-instance" xsi:noNamespaceSchemaLocation="library.xsd">
...
Note:
Declaring custom namespaces (and the Add Namespace command) is meaningful only
for target XML components, and applies to elements only. The Add Namespace
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
318
Data Sources and Targets
XML and XML schema
command is not available for attributes and wildcard nodes. It is also not available for
nodes which receive data by means of a Copy-All connection.
You can also declare multiple namespaces for the same element, if necessary. To do this, rightclick the node again, and select Add Namespace from the context menu. A new pair of
namespace and prefix nodes become available, to which you can connect the new prefix and
namespace values.
To remove a previously added namespace declaration, right-click the ns:namespace node, and
select Remove Namespace from the context menu.
Both the namespace and prefix input connectors must be mapped, even if you provide
empty values to them.
If you want to declare a default namespace (that is, one in the format
xmlns="mydefaultnamespace"), map an empty string value to prefix. To see this case in
action, edit the example mapping above so as to make the second constant an empty string.
The resulting output would then looks as follows:
<?xml version="1.0" encoding="UTF-8"?>
<library xmlns="altova.library" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance" xsi:noNamespaceSchemaLocation="library.xsd">
...
If you need to create prefixes for attribute names, for example <number
prod:id="prod557">557</number>, you can achieve this by either enabling dynamic access to
node's attributes (see Mapping Node Names), or by editing the schema so that it has a prod:id
attribute for <number>.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
7.2
Databases and MapForce
319
Databases and MapForce
Altova web site:
Mapping Database data
MapForce 2017 provides powerful support for mapping databases to XML, flat files, and other
database formats. With MapForce Enterprise edition, you can additionally map databases to EDI
formats, Excel 2007+, JSON, XBRL, and Web services.
The following databases are supported. The available root object for each database is also listed.
While Altova endeavors to support other databases, successful connection and data processing
have only been tested with the databases listed below. If your Altova application is a 64-bit
version, ensure that you have access to the 64-bit database drivers needed for the specific
database you are connecting to.
Database
Root Object
Firebird 2.5.4
database
IBM DB2 8.x, 9.1, 9.5, 9.7,
10.1, 10.5
schema
IBM DB2 for i 6.1, 7.1
schema
Logical files are supported and shown as
views.
IBM Informix 11.70
database
Informix supports connections via ADO, JDBC
and ODBC. The implementation does not
support large object data types in any of the
code generation languages. MapForce will
generate an error message (during code
generation) if any of these data types are
used.
Microsoft Access 2003, 2007,
2010, 2013
database
Microsoft Azure SQL
Database
database
Microsoft SQL Server 2005,
2008, 2012, 2014, 2016
database
MySQL 5.0, 5.1, 5.5, 5.6
database
Oracle 9i, 10g, 11g, 12c
schema
PostgreSQL 8.0, 8.1, 8.2, 8.3,
9.0.10, 9.1.6, 9.2.1, 9.4, 9.5
database
Progress OpenEdge 11.6
database
© 2017 Altova Gmb H
Notes
SQL Server 2016 codebase
PostgreSQL connections are supported both
as native connections and driver-based
connections through interfaces (drivers) such
as ODBC or JDBC. Native connections do not
require any drivers.
Altova MapForce 2017 Professional Edition
320
Data Sources and Targets
Databases and MapForce
SQLite 3.x
database
Sybase ASE15
database
SQLite connections are supported as native,
direct connections to the SQLite database file.
No separate drivers are required.
Database mappings in various execution environments
When you generate program code from a mapping, or when you compile a mapping to MapForce
Server execution files, the database connection details saved with the generated files are adapted
to drivers applicable or supported for the chosen target environment, as shown in the table below.
For example, if the mapping transformation language is set to Java, ADO connections are
converted to JDBC when Java code is generated from the mapping.
When the mapping is executed in an environment other than MapForce, you will need to make
sure that the database connection details are meaningful on the machine which executes the
mapping (for example, the database driver is installed, the database path is correct, the database
server is accessible, etc.).
Some database connection types are not supported in some target environments, as shown in the
table below.
Connection
type/
Execution
Environment
C#
C++
Java
MapForce
Server on
Windows
MapForce
Server on
Linux/Mac
ADO
ADO bridge
As is
Converted to
JDBC
As is
Converted to
JDBC
ADO.NET
As is
User defined
Converted to
JDBC
As is
Converted to
JDBC
JDBC
User defined
User defined
As is
As is
As is
ODBC
ODBC bridge
ODBC bridge
Converted to
JDBC
As is
Converted to
JDBC
Native
PostgreSQL
Not supported Not supported Not supported As is
As is
Native
SQLite
Not supported Not supported Not supported As is
As is
Table legend:
"As is" means that the database connection type (for example, JDBC, ODBC) remains as
defined in MapForce.
"Converted to JDBC" means that the database connection will be converted into a JDBClike database connection URL.
"ADO bridge" or "ODBC bridge" means that the connection string remains as defined in
MapForce, but the generated code will use a suitable class which acts as an ADO bridge
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
321
(or ODBC bridge, respectively), for example, System.Data.OleDb.OleDbConnection or
System.Data.Odbc.OdbcConnection.
"User defined" means that, in order for the connection to work in generated code, you will
need to manually enter the connection details into the Database Component Settings
dialog box. Depending on the case, these connection details must be entered under
ADO/OLE-DB-specific settings or under JDBC-specific settings.
See also:
Database Connections on Linux and Mac
Compiling Mappings to MapForce Server Execution Files
Code Generator
7.2.1
Connecting to a Database
In the most simple case, a database can be a local file such as a Microsoft Access or SQLite
database file. In a more advanced scenario, a database may reside on a remote or network
database server which does not necessarily use the same operating system as the application
that connects to it and consumes data. For example, while MapForce runs on a Windows
operating system, the database from which you want to access data (for example, MySQL) might
run on a Linux machine.
To interact with various database types, both remote and local, MapForce relies on the data
connection interfaces and database drivers that are already available on your operating system or
released periodically by the major database vendors. In the constantly evolving landscape of
database technologies, this approach caters for better cross-platform flexibility and
interoperability.
The following diagram illustrates, in a simplified way, data connectivity options available between
MapForce (illustrated as a generic client application) and a data store (which may be a database
server or database file).
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
322
Data Sources and Targets
Databases and MapForce
* Direct native connections are supported for SQLite and PostgreSQL databases. To connect to
such databases, no additional drivers are required to be installed on your system.
As shown in the diagram above, MapForce can access any of the major database types through
the following data access technologies:
ADO (Microsoft® ActiveX® Data Objects), which, in its turn, uses an underlying OLE DB
(Object Linking and Embedding, Database) provider
ADO.NET (A set of libraries available in the Microsoft .NET Framework that enable
interaction with data)
JDBC (Java Database Connectivity)
ODBC (Open Database Connectivity)
Some ADO.NET providers are not supported or have limited support. See ADO.NET Support
Notes.
The data connection interface you should choose largely depends on your existing software
infrastructure. You will typically choose the data access technology and the database driver which
integrates tighter with the database system to which you want to connect. For example, to
connect to a Microsoft Access 2013 database, you would build an ADO connection string that
uses a native provider such as the Microsoft Office Access Database Engine OLE DB
Provider. To connect to Oracle, on the other hand, you may want to download and install the
latest JDBC, ODBC, or ADO.NET interfaces from the Oracle website.
While drivers for Windows products (such as Microsoft Access or SQL Server) may already be
available on your Windows operating system, they may not be available for other database types.
Major database vendors routinely release publicly available database client software and drivers
which provide cross-platform access to the respective database through any combination of ADO,
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
323
ADO.NET, ODBC, or JDBC. In addition to this, several third party drivers may be available for any
of the above technologies. In most cases, there is more than one way to connect to the required
database from your operating system, and, consequently, from MapForce. The available features,
performance parameters, and the known issues will typically vary based on the data access
technology or drivers used.
7.2.1.1
Starting the Database Connection Wizard
Whenever you take an action that requires a database connection, a wizard appears that guides
you through the steps required to set up the connection.
Before you go through the wizard steps, be aware that for some database types it is necessary to
install and configure separately several database prerequisites, such as a database driver or
database client software. These are normally provided by the respective database vendors, and
include documentation tailored to your specific Windows version. For a list of database drivers
grouped by database type, see Database Drivers Overview.
To add the database as a source or target component on a mapping:
On the Insert menu, click Database.
To add the database as a reusable global resource:
1.
2.
3.
On the Tools menu, click Global Resources.
Click Add, and then click Database.
Click Choose Database.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
324
Data Sources and Targets
Databases and MapForce
After you select a database type and click Next, the on-screen instructions will depend on the
database kind, technology (ADO, ODBC, JDBC) and driver used.
For examples applicable to each database type, see Database Connection Examples. For
instructions applicable to each database access technology, refer to the following topics:
Setting up an ADO Connection
Setting up an ADO.NET Connection
Setting up an ODBC Connection
Setting up a JDBC Connection
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
7.2.1.2
Databases and MapForce
325
Database Drivers Overview
The following table lists common database drivers you can use to connect to a particular
database through a particular data access technology. Note that this list does not aim to be either
exhaustive or prescriptive; you can use other native or third party alternatives in addition to the
drivers shown below.
Even though a number of database drivers are available by default on your Windows operating
system (highlighted in bold in the table below), you may still want or need to download an
alternative driver. For some databases, the latest driver supplied by the database vendor is likely
to perform better than the driver that shipped with the operating system.
With some exceptions, most database vendors provide database client software which normally
includes any required database drivers, or provide you with an option during installation to select
the drivers and components you wish to install. Database client software typically consists of
administration and configuration utilities used to simplify database administration and
connectivity, as well as documentation on how to install and configure the database client and
any of its components.
Configuring the database client correctly is crucial for establishing a successful connection to the
database. Before installing and using the database client software, it is strongly recommended to
read carefully the installation and configuration instructions of the database client, since they
typically vary for each database version and for each Windows version.
Database
Interface
Drivers
Firebird
ADO.NET
Firebird ADO.NET Data Provider (http://www.firebirdsql.org/en/
additional-downloads/)
JDBC
Firebird JDBC driver ( http://www.firebirdsql.org/en/jdbc-driver/ )
ODBC
Firebird ODBC driver ( http://www.firebirdsql.org/en/odbc-driver/ )
ADO
IBM OLE DB Provider for DB2
ADO.NET
IBM Data Server Provider for .NET
JDBC
IBM Data Server Driver for JDBC and SQLJ
ODBC
IBM DB2 ODBC Driver
IBM DB2
IBM DB2 for i
IBM Informix
© 2017 Altova Gmb H
ADO
IBM DB2 for i5/OS IBMDA400 OLE DB Provider
IBM DB2 for i5/OS IBMDARLA OLE DB Provider
IBM DB2 for i5/OS IBMDASQL OLE DB Provider
ADO.NET
.NET Framework Data Provider for IBM i
JDBC
IBM Toolbox for Java JDBC Driver
ODBC
iSeries Access ODBC Driver
ADO
IBM Informix OLE DB Provider
JDBC
IBM Informix JDBC Driver
Altova MapForce 2017 Professional Edition
326
Data Sources and Targets
Database
Microsoft
Access
Interface
Drivers
ODBC
IBM Informix ODBC Driver
ADO
ADO.NET
Microsoft
SQL Server
MySQL
Oracle
Databases and MapForce
Microsoft Jet OLE DB Provider
Microsoft Access Database Engine OLE DB Provider
.NET Framework Data Provider for OLE DB
ODBC
Microsoft Access Driver
ADO
Microsoft OLE DB Provider for SQL Server
SQL Server Native Client
ADO.NET
.NET Framework Data Provider for SQL Server
.NET Framework Data Provider for OLE DB
JDBC
Microsoft JDBC Driver for SQL Server ( http://
msdn.microsoft.com/en-us/data/aa937724.aspx )
ODBC
SQL Server Native Client
ADO.NET
Connector/NET (http://dev.mysql.com/downloads/connector/net/)
JDBC
Connector/J ( http://dev.mysql.com/downloads/connector/j/ )
ODBC
Connector/ODBC ( http://dev.mysql.com/downloads/connector/
odbc/ )
ADO
Oracle Provider for OLE DB
Microsoft OLE DB Provider for Oracle
ADO.NET
Oracle Data Provider for .NET (http://www.oracle.com/technetwork/
topics/dotnet/index-085163.html)
JDBC
JDBC Thin Driver
JDBC Oracle Call Interface (OCI) Driver
These drivers are typically installed during the installation of your
Oracle database client. Connect through the OCI Driver (not the
Thin Driver) if you are using the Oracle XML DB component.
ODBC
PostgreSQL
Progress
OpenEdge
Microsoft ODBC for Oracle
Oracle ODBC Driver (typically installed during the installation of
your Oracle database client)
JDBC
Postgre JDBC Driver ( https://jdbc.postgresql.org/download.html )
ODBC
psqlODBC ( https://odbc.postgresql.org/ )
Native
Connectio
n
Yes
JDBC
JDBC Connector ( https://www.progress.com/jdbc/openedge )
ODBC
ODBC Connector ( https://www.progress.com/odbc/openedge )
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
Database
Interface
Drivers
SQLite
Native
Connectio
n
Yes
Sybase
ADO
Sybase ASE OLE DB Provider
JDBC
jConnect™ for JDBC
ODBC
Sybase ASE ODBC Driver
327
* The drivers highlighted in b old are Microsoft-supplied. If not already availab le on Windows system,
they can b e downloaded from the official Microsoft web site.
Some ADO.NET providers are not supported or have limited support. See ADO.NET Support
Notes.
To understand the capabilities and limitations of each data access technology with respect to
each database type, refer to the documentation of that particular database product and also test
the connection against your specific environment. To avoid common connectivity issues, consider
the following general notes and recommendations:
Since 32-bit and 64-bit drivers may not be compatible, make sure to install and configure
the driver version applicable to your Altova application. For example, if you are using a 32bit Altova application on a 64-bit operating system, set up your database connection
using the 32-bit driver version.
The latest driver versions may provide features not available in older editions.
When setting up an ODBC data source, it is generally recommended to create the data
source name (DSN) as System DSN instead of User DSN.
When setting up a JDBC data source, ensure that JRE (Java Runtime Environment) is
installed and that the CLASSPATH environment variable of the operating system is
configured.
For the support details and known issues applicable to Microsoft-supplied database
drivers, refer to the MSDN documentation.
For the installation instructions and support details of any drivers or database client
software that you install from a database vendor, check the documentation provided with
the installation package. Whether you are using an official or third party database driver,
the most comprehensive information and the configuration procedures applicable to that
specific driver on your specific operating system is normally part of the driver installation
package.
7.2.1.3
Setting up an ADO Connection
Microsoft ActiveX Data Objects (ADO) is a data access technology that enables you to connect
to a variety of data sources through OLE DB. OLE DB is an alternative interface to ODBC or
JDBC; it provides uniform access to data in a COM (Component Object Model) environment. ADO
is the typical choice for connecting to Microsoft native databases such as Microsoft Access or
SQL Server, although you can also use it for other data sources.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
328
Data Sources and Targets
Databases and MapForce
To set up an ADO connection:
1.
2.
Start the database connection wizard.
Click ADO Connections.
3.
Click Build.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
4.
Databases and MapForce
329
Select the data provider through which you want to connect. The table below lists a few
common scenarios.
To connect to this
database...
Microsoft Access
Use this provider...
Microsoft Office Access Database Engine OLE DB
Provider
When connecting to Microsoft Access 2003, you can
also use the Microsoft Jet OLE DB Provider.
SQL Server
Other database
SQL Server Native Client
Microsoft OLE DB Provider for SQL Server
Select the provider applicable to your database.
If an OLE DB provider to your database is not available,
install the required driver from the database vendor (see
Database Drivers Overview ). Alternatively, set up an
ODBC or JDBC connection.
If the operating system has an ODBC driver to the
required database, you can also use the Microsoft OLE
DB Provider for ODBC Drivers.
5.
Click Next and complete the wizard.
The subsequent wizard steps are specific to the provider you chose. For SQL Server, you will
need to provide or select the host name of the database server, as well as the database username
and password. For Microsoft Access, you will be asked to browse for or provide the path to the
database file.
The complete list of initialization properties (connection parameters) is available in the All tab of
the connection dialog box—these properties vary depending on the chosen provider. The following
sections provide guidance on configuring the basic initialization properties for Microsoft Access
and SQL Server databases:
Setting up the SQL Server Data Link Properties
Setting up the Microsoft Access Data Link Properties
Connecting to an Existing Microsoft Access Database
This approach is suitable when you want to connect to a Microsoft Access database which is not
password-protected. If the database is password-protected, set up the database password as
shown in Connecting to Microsoft Access (ADO).
To connect to an existing Microsoft Access database:
1.
2.
3.
Run the database connection wizard (see Starting the Database Connection Wizard).
Select Microsoft Access (ADO), and then click Next.
Browse for the database file, or enter the path to it (either relative or absolute) .
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
330
Data Sources and Targets
4.
Databases and MapForce
Click Connect.
Setting up the SQL Server Data Link Properties
When you connect to a Microsoft SQL Server database through ADO (see Setting up an ADO
Connection), ensure that the following data link properties are configured correctly in the All tab of
the Data Link Properties dialog box.
Data Link Properties dialog b ox
Property
Notes
Integrated Security
If you selected the SQL Server Native Client data provider
on the Provider tab, set this property to a space character.
Persist Security Info
Set this property to True.
Setting up the Microsoft Access Data Link Properties
When you connect to a Microsoft Access database through ADO (see Setting up an ADO
Connection), ensure that the following properties are configured correctly in the All tab of the Data
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
331
Link Properties dialog box.
Data Link Properties dialog b ox
Property
Notes
Data Source
This property stores the path to the Microsoft Access
database file. To avoid database connectivity issues, it is
recommended to use the UNC (Universal Naming Convention)
path format, for example:
\\anyserver\share$\filepath
Jet OLEDB:System
Database
This property stores the path to the workgroup information file.
You may need to explicitly set the value of this property
before you can connect to a Microsoft Access database.
If you cannot connect due to a "workgroup information file"
error, locate the workgroup information file (System.MDW)
applicable to your user profile (see http://
support.microsoft.com/kb/305542 for instructions), and set the
property value to the path of the System.MDW file.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
332
7.2.1.4
Data Sources and Targets
Databases and MapForce
Property
Notes
Jet OLEDB:Database
Password
If the database is password-protected, set the value of this
property to the database password.
Setting up an ADO.NET Connection
ADO.NET is a set of Microsoft .NET Framework libraries designed to interact with data, including
data from databases. To connect to a database from MapForce through ADO.NET, Microsoft
.NET Framework 4 or later is required. As shown below, you connect to a database through
ADO.NET by selecting a .NET provider and supplying a connection string.
A .NET data provider is a collection of classes that enables connecting to a particular type of data
source (for example, a SQL Server, or an Oracle database), executing commands against it, and
fetching data from it. In other words, with ADO.NET, an application such as MapForce interacts
with a database through a data provider. Each data provider is optimized to work with the specific
type of data source that it is designed for. There are two types of .NET providers:
1.
2.
Supplied by default with Microsoft .NET Framework.
Supplied by major database vendors, as an extension to the .NET Framework. Such
ADO.NET providers must be installed separately and can typically be downloaded from
the website of the respective database vendor.
Note: Certain ADO.NET providers are not supported or have limited support. See ADO.NET
Support Notes.
To set up an ADO.NET connection:
1.
2.
Start the database connection wizard.
Click ADO.NET Connections.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
3.
Databases and MapForce
333
Select a .NET data provider from the list.
The list of providers available by default with the .NET Framework appears in the
"Provider" list. Vendor-specific .NET data providers are available in the list only if they
are already installed on your system. To become available, vendor-specific .NET
providers must be installed into the GAC (Global Assembly Cache), by running the
.msi or .exe file supplied by the database vendor.
4.
Enter a database connection string. A connection string defines the database connection
information, as semicolon-delimited key/value pairs of connection parameters. For
example, a connection string such as Data Source=DBSQLSERV;Initial
Catalog=ProductsDB;User ID=dbuser;Password=dbpass connects to the SQL Server
database ProductsDB on server DBSQLSERV, with the user name dbuser and password
dbpass. You can create a connection string by typing the key/value pairs directly into the
"Connection String" dialog box. Another option is to create it with Visual Studio (see
Creating a Connection String in Visual Studio).
The syntax of the connection string depends on the provider selected from the
"Provider" list. For examples, see Sample ADO.NET Connection Strings.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
334
Data Sources and Targets
5.
Databases and MapForce
Click Connect.
Creating a Connection String in Visual Studio
In order to connect to a data source using ADO.NET, a valid database connection string is
required. The following instructions show you how to create a connection string from Visual
Studio.
To create a connection string in Visual Studio:
1.
2.
On the Tools menu, click Connect to Database.
Select a data source from the list (in this example, Microsoft SQL Server). The Data
Provider is filled automatically based on your choice.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
3.
Databases and MapForce
335
Click Continue.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
336
Data Sources and Targets
4.
5.
Databases and MapForce
Enter the server host name and the user name and password to the database. In this
example, we are connecting to the database ProductsDB on server DBSQLSERV, using
SQL Server authentication.
Click OK.
If the database connection is successful, it appears in the Server Explorer window. You can
display the Server Explorer window using the menu command View | Server Explorer. To obtain
the database connection string, right-click the connection in the Server Explorer window, and
select Properties. The connection string is now displayed in the Properties window of Visual
Studio. Note that, before pasting the string into the "Connection String" box of MapForce, you will
need to replace the asterisk ( * ) characters with the actual password.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
337
Sample ADO.NET Connection Strings
To set up an ADO.NET connection, you need to select an ADO.NET provider from the database
connection dialog box and enter a connection string (see also Setting up an ADO.NET
Connection). Sample ADO.NET connection strings for various databases are listed below under
the .NET provider where they apply.
.NET Framework Data Provider for IBM i
This provider is installed as part of IBM i Access Client Solutions - Windows Application Pack age.
A sample connection string looks as follows:
DataSource=ServerAddress;UserID=user;Password=password;DataCompression=True;
For more information, see the ".NET Provider Technical Reference" help file included in the
installation package above.
.NET Framework Data Provider for MySQL
This provider can be downloaded from MySQL website (https://dev.mysql.com/downloads/
connector/net/). A sample connection string looks as follows:
Server=127.0.0.1;Uid=root;Pwd=12345;Database=test;
See also: https://dev.mysql.com/doc/connector-net/en/connector-net-programming-connectingconnection-string.html
.NET Framework Data Provider for SQL Server
A sample connection string looks as follows:
Data Source=DBSQLSERV;Initial Catalog=ProductsDB;User
ID=dbuser;Password=dbpass
See also: https://msdn.microsoft.com/en-us/library/ms254500(v=vs.110).aspx
IBM DB2 Data Provider 10.1.2 for .NET Framework 4.0
Database=PRODUCTS;UID=user;Password=password;Server=localhost:50000;
Note:
This provider is typically installed with the IBM DB2 Data Server Client package. If the
provider is missing from the list of ADO.NET providers after installing IBM DB2 Data
Server Client package, refer to the following technical note: http://www-01.ibm.com/
support/docview.wss?uid=swg21429586.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
338
Data Sources and Targets
Databases and MapForce
See also: http://www.ibm.com/support/knowledgecenter/en/SSEPGG_10.1.0/
com.ibm.swg.im.dbclient.adonet.ref.doc/doc/DB2ConnectionClassConnectionStringProperty.html
Oracle Data Provider for .NET (ODP.NET)
The installation package which includes the ODP.NET provider can be downloaded from Oracle
website (see http://www.oracle.com/technetwork/topics/dotnet/downloads/index.html). A sample
connection string looks as follows:
Data Source=DSORCL;User Id=user;Password=password;
Where DSORCL is the name of the data source which points to an Oracle service name defined in
the tnsnames.ora file, as described in Connecting to Oracle (ODBC).
To connect without configuring a service name in the tnsnames.ora file, use a string such as:
Data Source=(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=host)
(PORT=port)))(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=MyOracleSID)));User
Id=user;Password=password;
See also: https://docs.oracle.com/cd/B28359_01/win.111/b28375/featConnecting.htm
ADO.NET Support Notes
The following table lists known ADO.NET database drivers that are currently not supported or have
limited support in MapForce.
Database
Driver
Support notes
All databases
.Net Framework Data
Provider for ODBC
Limited support. Known issues exist
with Microsoft Access connections. It
is recommended to use ODBC direct
connections instead. See Setting up an
ODBC Connection.
.Net Framework Data
Provider for OleDb
Limited support. Known issues exist
with Microsoft Access connections. It
is recommended to use ADO direct
connections instead. See Setting up an
ADO Connection.
Firebird
Firebird ADO.NET Data
Provider
Limited support. It is recommended to
use ODBC or JDBC instead. See
Connecting to Firebird (ODBC) and
Connecting to Firebird (JDBC).
Informix
IBM Informix Data Provider
for .NET Framework 4.0
Not supported. Use DB2 Data Server
Provider instead.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
7.2.1.5
Databases and MapForce
Database
Driver
Support notes
IBM DB2 for i
(iSeries)
.Net Framework Data
Provider for i5/OS
Not supported. Use .Net Framework
Data Provider for IBM i instead,
installed as part of the IBM i Access
Client Solutions - Windows Application
Pack age.
Oracle
.Net Framework Data
Provider for Oracle
Limited support. Although this driver is
provided with the .NET Framework, its
usage is discouraged by Microsoft,
because it is deprecated.
PostgreSQL
-
No ADO.NET drivers for this vendor are
supported.
Sybase
-
No ADO.NET drivers for this vendor are
supported.
339
Setting up an ODBC Connection
ODBC (Open Database Connectivity) is a widely used data access technology that enables you
to connect to a database from MapForce. It can be used either as primary means to connect to a
database, or as an alternative to OLE DB- or JDBC-driven connections.
To connect to a database through ODBC, first you need to create an ODBC data source name
(DSN) on the operating system. This step is not required if the DSN has already been created,
perhaps by another user of the operating system. The DSN represents a uniform way to describe
the database connection to any ODBC-aware client application on the operating system, including
MapForce. DSNs can be of the following types:
System DSN
User DSN
File DSN
A System data source is accessible by all users with privileges on the operating system. A User
data source is available to the user who created it. Finally, if you create a File DSN, the data
source will be created as a file with the .dsn extension which you can share with other users,
provided that they have installed the drivers used by the data source.
Any DSNs already available on your machine are listed by the database connection dialog box
when you click ODBC connections on the ODBC connections dialog box.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
340
Data Sources and Targets
Databases and MapForce
ODBC Connections dialog b ox
If a DSN to the required database is not available, the MapForce database connection wizard will
assist you to create it; however, you can also create it directly on your Windows operating
system. In either case, before you proceed, ensure that the ODBC driver applicable for your
database is in the list of ODBC drivers available to the operating system (see Viewing the
Available ODBC Drivers ).
To connect by using a new DSN:
1.
2.
3.
Start the database connection wizard.
On the database connection dialog box, click ODBC Connections.
Select a data source type (User DSN, System DSN, File DSN).
To create a System DSN, you need administrative rights on the operating system.
4.
5.
6.
Click Add
.
Select a driver, and then click User DSN or System DSN (depending on the type of the
DSN you want to create). If the driver applicable to your database is not listed, download
it from the database vendor and install it (see Database Drivers Overview ).
On the dialog box that pops up, fill in any driver specific connection information to
complete the setup.
For the connection to be successful, you will need to provide the host name (or IP address) of the
database server, as well as the database username and password. There may be other optional
connection parameters—these parameters vary between database providers. For detailed
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
341
information about the parameters specific to each connection method, consult the documentation
of the driver provider. Once created, the DSN becomes available in the list of data source names.
This enables you to reuse the database connection details any time you want to connect to the
database. Note that User DSNs are added to the list of User DSNs whereas System DSNs are
added to the list of System DSNs.
To connect by using an existing DSN:
1.
2.
3.
4.
Start the database connection wizard.
Click ODBC Connections.
Choose the type of the existing data source (User DSN, System DSN, File DSN).
Click the existing DSN record, and then click Connect.
To build a connection string based on an existing .dsn file:
1.
2.
3.
4.
5.
Start the database connection wizard.
Click ODBC Connections.
Select Build a connection string, and then click Build.
If you want to build the connection string using a File DSN, click the File Data Source
tab. Otherwise, click the Machine Data Source tab. (System DSNs and User DSNs are
known as "Machine" data sources.)
Select the required .dsn file, and then click OK.
To connect by using a prepared connection string:
1.
2.
3.
4.
Start the database connection wizard.
Click ODBC Connections.
Select Build a connection string.
Paste the connection string into the provided box, and then click Connect.
Viewing the Available ODBC Drivers
You can view the ODBC drivers available on your operating system in the ODBC Data Source
Administrator. You can access the ODBC Data Source Administrator (Odbcad32.exe) from the
Windows Control Panel, under Administrative Tools. On 64-bit operating systems, there are two
versions of this executable:
The 32-bit version of the Odbcad32.exe file is located in the C:\Windows\SysWoW64
directory (assuming that C: is your system drive).
The 64-bit version of the Odbcad32.exe file is located in the C:\Windows\System32
directory.
Any installed 32-bit database drivers are visible in the 32-bit version of ODBC Data Source
Administrator, while 64-bit drivers—in the 64-bit version. Therefore, ensure that you check the
database drivers from the relevant version of ODBC Data Source Administrator.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
342
Data Sources and Targets
Databases and MapForce
ODBC Data Source Administrator
If the driver to your target database does not exist in the list, or if you want to add an alternative
driver, you will need to download it from the database vendor (see Database Drivers Overview ).
Once the ODBC driver is available on your system, you are ready to create ODBC connections
with it (see Setting up an ODBC Connection ).
7.2.1.6
Setting up a JDBC Connection
JDBC (Java Database Connectivity) is a database access interface which is part of the Java
software platform from Oracle. JDBC connections are generally more resource-intensive than
ODBC connections but may provide features not available through ODBC.
Prerequisites
JRE (Java Runtime Environment) or Java Development Kit (JDK) must be installed. If you
have not installed it already, check the official Java website for the download package and
installation instructions.
The JDBC drivers from the database vendor must be installed. If you are connecting to an
Oracle database, note that some Oracle drivers are specific to certain JRE versions and
may require additional components and configuration. The documentation of your Oracle
product (for example, the "Oracle Database JDBC Developer's Guide and Reference")
includes detailed instructions about the configuration procedure for each JDBC driver.
The operating system's PATH environment variable must include the path to the bin
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
343
directory of the JRE or JDK installation directory, for example C:\Program Files (x86)
\Java\jre1.8.0_51\bin.
The CLASSPATH environment variable must include the path to the JDBC driver (one or
several .jar files) on your Windows operating system. When you install some database
clients, the installer may configure this variable automatically. The documentation of the
JDBC driver will typically include step-by-step instructions on setting the CLASSPATH
variable (see also Configuring the CLASSPATH).
Setting up a JDBC connection
1.
2.
3.
Start the database connection wizard.
Click JDBC Connections.
Optionally, enter a semicolon-separated list of .jar file paths in the "Classpaths" text box.
The .jar libraries entered here will be loaded into the environment in addition to those
already defined in the CLASSPATH environment variable. When you finish editing the
"Classpaths" text box, any JDBC drivers found in the source .jar libraries are
automatically added to the "Driver" list (see the next step).
4.
Next to "Driver", select a JDBC driver from the list, or enter a Java class name. Note that
this list contains any JDBC drivers configured through the CLASSPATH environment variable
(see Configuring the CLASSPATH), as well as those found in the "Classpaths" text box.
The JDBC driver paths defined in the CLASSPATH variable, as well as any .jar file
paths entered directly in the database connection dialog box are all supplied to the
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
344
Data Sources and Targets
Databases and MapForce
Java Virtual Machine (JVM). The JVM then decides which drivers to use in order to
establish a connection. It is recommended to keep track of Java classes loaded into
the JVM so as not to create potential JDBC driver conflicts and avoid unexpected
results when connecting to the database.
5.
6.
Note:
7.
Enter the username and password to the database in the corresponding boxes.
In the Database URL text box, enter the JDBC connection URL (string) in the format
specific to your database type. The following table describes the syntax of JDBC
connection URLs (strings) for common database types.
Database
JDBC Connection URL
Firebird
jdbc:firebirdsql://<host>[:<port>]/<database path
or alias>
IBM DB2
jdbc:db2://hostName:port/databaseName
IBM Informix
jdbc:informix-sqli://hostName:port/
databaseName:INFORMIXSERVER=myserver
Microsoft SQL Server
jdbc:sqlserver://hostName:port;databaseName=name
MySQL
jdbc:mysql://hostName:port/databaseName
Oracle
jdbc:oracle:thin:@//hostName:port:service
Oracle XML DB
jdbc:oracle:oci:@//hostName:port:service
PostgreSQL
jdbc:postgresql://hostName:port/databaseName
Progress OpenEdge
jdbc:datadirect:openedge://
host:port;databaseName=db_name
Sybase
jdbc:sybase:Tds:hostName:port/databaseName
Syntax variations to the formats listed above are also possible (for example, the database
URL may exclude the port or may include the username and password to the database).
Check the documentation of the database vendor for further details.
Click Connect.
Configuring the CLASSPATH
The CLASSPATH environment variable is used by the Java Runtime Environment (JRE) to locate
Java classes and other resource files on your operating system. When you connect to a database
through JDBC, this variable must be configured to include the path to the JDBC driver on your
operating system, and, in some cases, the path to additional library files specific to the database
type you are using.
The following table lists sample file paths that must be typically included in the CLASSPATH
variable. Importantly, you may need to adjust this information based on the location of the JDBC
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
345
driver on your system, the JDBC driver name, as well as the JRE version present on your
operating system. To avoid connectivity problems, check the installation instructions and any preinstallation or post-installation configuration steps applicable to the JDBC driver installed on your
operating system.
Database
Sample CLASSPATH entries
Firebird
C:\Program Files\Firebird\Jaybird-2.2.8-JDK_1.8\jaybirdfull-2.2.8.jar
IBM DB2
C:\Program Files (x86)\IBM\SQLLIB\java\db2jcc.jar;C:
\Program Files (x86)\IBM\SQLLIB\java
\db2jcc_license_cu.jar;
IBM Informix
C:\Informix_JDBC_Driver\lib\ifxjdbc.jar;
Microsoft SQL Server
C:\Program Files\Microsoft JDBC Driver 4.0 for SQL
Server\sqljdbc_4.0\enu\sqljdbc.jar
MySQL
mysql-connector-java-version-bin.jar;
Oracle
ORACLE_HOME\jdbc\lib\ojdbc6.jar;
Oracle (with XML DB)
ORACLE_HOME\jdbc\lib\ojdbc6.jar;ORACLE_HOME\LIB
\xmlparserv2.jar;ORACLE_HOME\RDBMS\jlib\xdb.jar;
PostgreSQL
<installation directory>\postgresql.jar
Progress OpenEdge
%DLC%\java\openedge.jar;%DLC%\java\pool.jar;
Note: Assuming the Progress OpenEdge SDK is installed on the
machine, %DLC% is the directory where OpenEdge is installed.
Sybase
C:\sybase\jConnect-7_0\classes\jconn4.jar
Changing the CLASSPATH variable may affect the behavior of Java applications on your
machine. To understand possible implications before you proceed, refer to the Java
documentation.
Environment variables can be user or system. To change system environment variables,
you need administrative rights on the operating system.
After you change the environment variable, restart any running programs for settings to take
effect. Alternatively, log off or restart your operating system.
To configure the CLASSPATH on Windows 7:
1.
2.
3.
4.
5.
6.
Open the Start menu and right-click Computer.
Click Properties.
Click Advanced system settings.
In the Advanced tab, click Environment Variables,
Locate the CLASSPATH variable under user or system environment variables, and then
click Edit. If the CLASSPATH variable does not exist, click New to create it.
Edit the variable value to include the path on your operating system where the JDBC
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
346
Data Sources and Targets
Databases and MapForce
driver is located. To separate the JDBC driver path from other paths that may already be
in the CLASSPATH variable, use the semi-colon separator ( ; ).
To configure the CLASSPATH on Windows 8, Windows 10:
1.
2.
3.
4.
5.
7.2.1.7
Right-click the Windows Start button, and then click System.
Click Advanced System Settings.
Click Environment Variables.
Locate the CLASSPATH variable under user or system environment variables, and then
click Edit. If the CLASSPATH variable does not exist, click New to create it.
Edit the variable value to include the path on your operating system where the JDBC
driver is located. To separate the JDBC driver path from other paths that may already be
in the CLASSPATH variable, use the semi-colon separator ( ; ).
Setting up a PostgreSQL Connection
Connections to PostgreSQL databases can be set up either as native connections, or
connections via ODBC, JDBC, and other drivers. The advantage of setting up a native connection
is that no drivers are required to be installed on your system. Also, if you intend to deploy files for
execution on a Linux or OS X server, no drivers are required to be installed on the target server as
well (see also Database Connections on Linux and Mac).
If, for any reason, you prefer to establish a connection by means of a driver, see the Database
Drivers Overview. For information about connections through JDBC, see Setting up a JDBC
Connection. For an example of connecting to PostgreSQL through ODBC, see Connecting to
PostgreSQL (ODBC).
Otherwise, if you want to set up a native connection to PostgreSQL, follow the steps below. To
proceed, you need the following prerequisites: host name, port, database name, username, and
password.
To set up a native PostgreSQL connection:
1.
2.
3.
Start the database connection wizard.
Click PostgreSQL Connections.
Enter the host (localhost, if PostgreSQL runs on the same machine), port (typically 5432,
this is optional), the database name, username, and password in the corresponding
boxes.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
4.
Databases and MapForce
347
Click Connect.
If the PostgreSQL database server is on a different machine, note the following:
The PostgreSQL database server must be configured to accept connections from clients.
Specifically, the pg_hba.conf file must be configured to allow non-local connections.
Secondly, the postgresql.conf file must be configured to listen on specified IP
address(es) and port. For more information, check the PostgreSQL documentation
(https://www.postgresql.org/docs/9.5/static/client-authentication-problems.html).
The server machine must be configured to accept connections on the designated port
(typically, 5432) through the firewall. For example, on a database server running on
Windows, a rule may need to be created to allow connections on port 5432 through the
firewall, from Control Panel > Windows Firewall > Advanced Settings > Inbound
Rules.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
348
7.2.1.8
Data Sources and Targets
Databases and MapForce
Setting up a SQLite Connection
SQLite (http://www.sqlite.org) is a file-based, self-contained database type, which makes it ideal
in scenarios where portability and ease of configuration is important. Since SQLite databases are
natively supported by MapForce, you do not need to install any drivers to connect to them. Also,
note the following:
SQLite databases are supported in the MapForce BUILT-IN transformation language
(either when you preview the mapping or when you run a MapForce Server execution file).
SQLite databases are not supported in user-defined functions (UDF).
On Linux, statement execution timeout for SQLite databases is not supported.
Full text search tables are not supported
SQLite allows values of different data types in each row of a given table. In MapForce, all
processed values must be compatible with the declared column type; therefore, run-time
errors may occur if your SQLite database has row values which are not the same as the
declared column type.
If your mapping should write data to a SQLite database, and if you don't have the target
database file already, you will need to create it separately. In this case, you can either
create it with a tool such as DatabaseSpy (http://www.altova.com/databasespy.html ) or
download the SQLite command-line shell from the official website, and create the
database file from the command line (see also Example: Mapping data from XML to
SQLite). For complete reference to SQLite command syntax, refer to the official SQLite
documentation.
Connecting to an Existing SQLite Database
To connect to an existing SQLite database:
1.
2.
3.
4.
Run the database connection wizard (see Starting the Database Connection Wizard).
Select SQLite, and then click Next.
Browse for the SQLite database file, or enter the path (either relative or absolute) to the
database. The Connect button becomes enabled once you enter the path to a SQLite
database file.
Click Connect.
Example: Mapping data from XML to SQLite
This example walks you through the steps required to create a MapForce mapping which reads
data from an XML file and writes it to a SQLite database. The example is accompanied by a
sample mapping design (.mfd) file. If you want to look at the sample file before starting this
example, you can open it from the following path: <Documents>\Altova\MapForce2017
\MapForceExamples\Tutorial\XMLtoSQLite.mfd.
The goal of the example is to insert data from an XML file into a SQLite database. To accomplish
the goal of the example, you will need an empty SQLite database to which data will be written.
For the scope of this example, you will create the SQLite database with the command-line shell
available from the official SQLite website, although this can be done with other tools as well (for
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
349
example, Altova DatabaseSpy).
To create the SQLite database:
1.
2.
Download the SQLite command-line shell for Windows from the SQLite download page
(http://www.sqlite.org/download.html) and unpack the .zip archive to a directory on your
local machine (for the scope of this example, use c:\sqlite).
Run c:\sqlite\sqlite3.exe and enter the following statement:
create table articles (number smallint, name varchar(10), singleprice
real);
3.
This creates the table articles in the in-memory database. The table articles consists
of three columns: number, name, and singleprice. The purpose of these columns is to
store data from the elements with the same name defined in the source XML schema.
Each column is declared with a data type suitable for the data expected to be stored in
that column.
Run the command:
.save Articles.db
This saves the in-memory database to the current working path: c:\sqlite\Articles.db.
Note that you will need to refer to this path in subsequent steps.
To create the XML to SQLite mapping design:
1.
2.
3.
Run MapForce and make sure that the transformation language is set to BUILT-IN (use
the menu command Output | Built-in Execution Engine).
Add to the mapping area the file Articles.xml located in the <Documents>\Altova
\MapForce2017\MapForceExamples\Tutorial folder (use the menu command File |
Insert XML Schema/File).
Add to the mapping area the database Articles.db created in previous steps (use the
menu command File | Insert Database), and then select SQLite.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
350
Data Sources and Targets
Databases and MapForce
4.
When prompted to choose the database objects, select the articles table.
5.
Draw the connections as shown below:
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
6.
Click the A:In button on the database component and select the Delete All records
option. This ensures that, every time the mapping is executed, all existing database rows
are first deleted, in order to prevent duplication.
7.
Click the Output tab of the main mapping window. MapForce executes the mapping
using the built-in execution engine and displays the create SQL query in the Output
window.
© 2017 Altova Gmb H
351
Altova MapForce 2017 Professional Edition
352
Data Sources and Targets
8.
Databases and MapForce
Run the SQL script to populate the database (use the menu command Output | Run
SQL-Script). If MapForce does not encounter any runtime errors, the records are inserted
into the SQLite database.
To check whether data was correctly inserted into the SQLite database:
1.
Run the file c:\sqlite\sqlite3.exe and open the database with the command:
.open Articles.db
2.
Run the following select statement:
select * from articles;
This query returns all the records in the articles table, separated by the broken bar ( ¦ )
character, as follows:
As shown above, the query returns four rows. This corresponds to the number of records
in the source XML file, which was the intended goal of this example.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
7.2.1.9
Databases and MapForce
353
Using a Connection from Global Resources
If you have previously configured a database connection to be available as a global resource, you
can reuse the connection at any time (even across different Altova applications).
To use a database connection from Global Resources:
1.
2.
Start the database connection wizard.
Click Global Resources. Any database connections available as global resources are
listed.
3.
Select the database connection record, and click Connect.
Tip:
7.2.1.10
To get additional information about each global resource, move the mouse cursor over the
global resource.
Database Connection Examples
This section includes sample procedures for connecting to a database from MapForce. Note that
your Windows machine, the network environment, and the database client or server software is
likely to have a configuration that is not exactly the same as the one presented in the following
examples.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
354
Data Sources and Targets
Note:
Databases and MapForce
For most database types, it is possible to connect using more than one data access
technology (ADO, ODBC, JDBC) or driver. The performance of the database connection,
as well as its features and limitations will depend on the selected driver, database client
software (if applicable), and any additional connectivity parameters that you may have
configured outside MapForce.
Connecting to Firebird (ODBC)
This topic provides sample instructions for connecting to a Firebird 2.5.4 database running on a
Linux server.
Prerequisites:
The Firebird database server is configured to accept TCP/IP connections from clients.
The Firebird ODBC driver must be installed on your operating system. This example uses
the Firebird ODBC driver version 2.0.3.154 downloaded from the Firebird website ( http://
www.firebirdsql.org/ ).
The Firebird client must be installed on your operating system. Note that there is no
standalone installer available for the Firebird 2.5.4 client; the client is part of the Firebird
server installation package. You can download the Firebird server installation package
from the Firebird website ( http://www.firebirdsql.org/ ), look for "Windows executable
installer for full Superclassic/Classic or Superserver". To install only the client files,
choose "Minimum client install - no server, no tools" when going through the wizard
steps.
Important:
The platform of both the Firebird ODBC driver and client (32-bit or 64-bit)
must correspond to that of MapForce.
The version of the Firebird client must correspond to the version of Firebird
server to which you are connecting.
You have the following database connection details: server host name or IP address,
database path (or alias) on the server, user name, and password.
To connect to Firebird via ODBC:
1.
2.
3.
Start the database connection wizard.
Click ODBC Connections.
Select User DSN (or System DSN, if you have administrative privileges), and then click
Add
.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
4.
Select the Firebird driver, and then click User DSN (or System DSN, depending on what
you selected in the previous step). If the Firebird driver is not available in the list, make
sure that it is installed on your operating system (see also Viewing the Available ODBC
Drivers ).
5.
Enter the database connection details as follows:
355
Data Source Name (DSN) Enter a descriptive name for the data source you are
creating.
Database
© 2017 Altova Gmb H
Enter the server host name or IP address, followed by a
Altova MapForce 2017 Professional Edition
356
Data Sources and Targets
Databases and MapForce
colon, followed by the database alias (or path). In this
example, the host name is firebirdserv, and the
database alias is products, as follows:
firebirdserv:products
Using a database alias assumes that, on the server side,
the database administrator has configured the alias
products to point to the actual Firebird (.fdb) database file
on the server (see the Firebird documentation for more
details).
You can also use the server IP address instead of the host
name, and a path instead of an alias; therefore, any of the
following sample connection strings are valid:
firebirdserver:/var/Firebird/databases/
butterflies.fdb
127.0.0.1:D:\Misc\Lenders.fdb
If the database is on the local Windows machine, click
Browse and select the Firebird (.fdb) database file directly.
6.
Client
Enter the path to the fbclient.dll file. By default, this is
the bin subdirectory of the Firebird installation directory.
Database Account
Enter the database user name supplied by the database
administrator (in this example, PROD_ADMIN).
Password
Enter the database password supplied by the database
administrator.
Click OK.
Connecting to Firebird (JDBC)
This topic provides sample instructions for connecting to a Firebird database server through
JDBC.
Prerequisites:
Java Runtime Environment (JRE) or Java Development Kit (JDK) must be installed on your
operating system.
The operating system's PATH environment variable must include the path to the bin
directory of the JRE or JDK installation directory, for example C:\Program Files (x86)
\Java\jre1.8.0_51\bin.
The Firebird JDBC driver must be available on your operating system (it takes the form of
a .jar file which provides connectivity to the database). The driver can be downloaded from
the Firebird website ( http://www.firebirdsql.org/ ). This example uses Jaybird 2.2.8.
You have the following database connection details: host, database path or alias,
username, and password.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
357
To connect to Firebird through JDBC:
1.
2.
3.
4.
5.
6.
Start the database connection wizard.
Click JDBC Connections.
Next to "Classpaths", enter the path to the .jar file which provides connectivity to the
database. If necessary, you can also enter a semicolon-separated list of .jar file paths. In
this example, the required .jar file is located at the following path: C:\jdbc\firebird
\jaybird-full-2.2.8.jar. Note that you can leave the "Classpaths" text box empty if you
have added the .jar file path(s) to the CLASSPATH environment variable of the operating
system (see also Configuring the CLASSPATH).
In the "Driver" box, select org.firebirdsql.jdbc.FBDriver. Note that this entry is available
if a valid .jar file path is found either in the "Classpath" text box, or in the operating
system's CLASSPATH environment variable (see the previous step).
Enter the username and password to the database in the corresponding text boxes.
Enter the connection string to the database server in the Database URL text box, by
replacing the highlighted values with the ones applicable to your database server.
jdbc:firebirdsql://<host>[:<port>]/<database path or alias>
7.
Click Connect.
Connecting to IBM DB2 (ODBC)
This topic provides sample instructions for connecting to an IBM DB2 database through ODBC.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
358
Data Sources and Targets
Databases and MapForce
Prerequisites:
IBM Data Server Client must be installed and configured on your operating system (this
example uses IBM Data Server Client 9.7). For installation instructions, check the
documentation supplied with your IBM DB2 software. After installing the IBM Data Server
Client, check if the ODBC drivers are available on your machine (see Viewing the
Available ODBC Drivers).
Create a database alias. There are several ways to do this:
o From IBM DB2 Configuration Assistant
o From IBM DB2 Command Line Processor
o From the ODBC data source wizard (for this case, the instructions are shown below)
You have the following database connection details: host, database, port, username, and
password.
To connect to IBM DB2:
1.
Start the database connection wizard and select IBM DB2 (ODBC/JDBC).
2.
Click Next.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
3.
Databases and MapForce
359
Select ODBC, and click Next. If prompted to edit the list of known drivers for the
database, select the database drivers applicable to IBM DB2 (see Prerequisites), and
click Next.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
360
Data Sources and Targets
4.
Databases and MapForce
Select the IBM DB2 driver from the list, and then click Connect. (To edit the list of
available drivers, click Edit Drivers, and then check or uncheck the IBM DB2 drivers you
wish to add or remove, respectively.)
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
5.
Enter a data source name (in this example, DB2DSN), and then click Add.
6.
On the Data Source tab, enter the user name and password to the database.
© 2017 Altova Gmb H
361
Altova MapForce 2017 Professional Edition
362
Data Sources and Targets
7.
Databases and MapForce
On the TCP/IP tab, enter the database name, a name for the alias, the host name and
the port number, and then click OK.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
8.
Databases and MapForce
363
Enter again the username and password, and then click OK.
Connecting to IBM DB2 for i (ODBC)
This topic provides sample instructions for connecting to an IBM DB2 for i database through
ODBC.
Prerequisites:
IBM System i Access for Windows must be installed on your operating system (this
example uses IBM System i Access for Windows V6R1M0). For installation instructions,
check the documentation supplied with your IBM DB2 for i software. After installation,
check if the ODBC driver is available on your machine (see Viewing the Available ODBC
Drivers).
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
364
Data Sources and Targets
Databases and MapForce
You have the following database connection details: the I.P. address of the database
server, database user name, and password.
Run System i Navigator and follow the wizard to create a new connection. When
prompted to specify a system, enter the I.P. address of the database server. After
creating the connection, it is recommended to verify it (click on the connection, and
select File > Diagnostics > Verify Connection). If you get connectivity errors, contact
the database server administrator.
To connect to IBM DB2 for i:
1.
2.
3.
Start the database connection wizard.
Click ODBC connections.
Click User DSN (alternatively, click System DSN, or File DSN, in which case the
subsequent instructions will be similar).
4.
5.
Click Add
.
Select the iSeries Access ODBC Driver from the list, and click User DSN (or System
DSN, if applicable).
6.
Enter a data source name and select the connection from the System combo box. In this
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
365
example, the data source name is iSeriesDSN and the System is 192.0.2.0.
Note:
7.
When adding an ODBC data source for an IBM DB2 for i database, a default flag is set
which enables query timeouts. This setting must be disabled for MapForce to correctly
load mapping files. To disable the setting, select the Performance tab, click Advanced,
and clear the Allow query timeout check box.
Click Connection Options, select Use the User ID specified below and enter the name
of the database user (in this example, DBUSER).
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
366
Data Sources and Targets
Databases and MapForce
8. Click OK. The new data source becomes available in the list of DSNs.
9. Click Connect.
10. Enter the user name and password to the database when prompted, and then click OK.
Connecting to IBM Informix (JDBC)
This topic provides sample instructions for connecting to an IBM Informix database server through
JDBC.
Prerequisites:
Java Runtime Environment (JRE) must be installed on your operating system.
The JDBC driver (one or several .jar files that provide connectivity to the database) must
be available on your operating system. In this example, IBM Informix JDBC driver version
3.70 is used. For the driver's installation instructions, see the documentation
accompanying the driver or the "IBM Informix JDBC Driver Programmer's Guide").
You have the following database connection details: host, name of the Informix server,
database, port, username, and password.
To connect to IBM Informix through JDBC:
1.
2.
3.
Start the database connection wizard.
Click JDBC Connections.
Next to "Classpaths", enter the path to the .jar file which provides connectivity to the
database. If necessary, you can also enter a semicolon-separated list of .jar file paths. In
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
4.
5.
6.
Databases and MapForce
367
this example, the required .jar file is located at the following path: C:
\Informix_JDBC_Driver\lib\ifxjdbc.jar. Note that you can leave the "Classpaths" text
box empty if you have added the .jar file path(s) to the CLASSPATH environment variable
of the operating system (see also Configuring the CLASSPATH).
In the "Driver" box, select com.informix.jdbc.IfxDriver. Note that this entry is available
if a valid .jar file path is found either in the "Classpath" text box, or in the operating
system's CLASSPATH environment variable (see the previous step).
Enter the username and password to the database in the corresponding text boxes.
Enter the connection string to the database server in the Database URL text box, by
replacing the highlighted values with the ones applicable to your database server.
jdbc:informix-sqli://hostName:port/
databaseName:INFORMIXSERVER=myserver;
7.
Click Connect.
Connecting to Microsoft Access (ADO)
A simple way to connect to a Microsoft Access database is to follow the wizard and browse for
the database file, as shown in Connecting to an Existing Microsoft Access Database. An
alternative approach is to set up an ADO connection explicitly, as shown in this topic. This
approach is useful if your database is password-protected.
It is also possible to connect to Microsoft Access through an ODBC connection, but there are
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
368
Data Sources and Targets
Databases and MapForce
some limitations in this scenario, so it is best to avoid it.
To connect to a password-protected Microsoft Access database:
1.
2.
3.
Start the database connection wizard.
Click ADO Connections.
Click Build.
4.
Select the Microsoft Office 15.0 Access Database Engine OLE DB Provider, and then
click Next.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
5.
6.
Note:
Databases and MapForce
369
In the Data Source box, enter the path to the Microsoft Access file. Because the file is on
the local network share U:\Departments\Finance\Reports\Revenue.accdb, we will
convert it to UNC format, and namely \\server1\\dfs\Departments\Finance\Reports
\Revenue.accdb, where server1 is the name of the server and dfs is the name of the
network share.
On the All tab, double click the Jet OLEDB:Database Password property and enter the
database password as property value.
If you are still unable to connect, locate the workgroup information file (System.MDW)
applicable to your user profile (see http://support.microsoft.com/kb/305542 for
instructions), and set the value of the Jet OLEDB: System database property to the path
of the System.MDW file.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
370
Data Sources and Targets
Databases and MapForce
Connecting to Microsoft SQL Server (ADO)
To connect to SQL Server using the Microsoft OLE DB Provider:
1.
Start the database connection wizard.
2.
Select Microsoft SQL Server (ADO), and then click Next. The list of available ADO
drivers is displayed.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
3.
Databases and MapForce
371
Select Microsoft OLE DB Provider for SQL Server, and then click Next.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
372
Data Sources and Targets
4.
5.
6.
7.
8.
Databases and MapForce
Select or enter the name of the database server (in this example, SQLSERV01). To view
the list of all servers on the network, expand the drop-down list.
If the database server was configured to allow connections from users authenticated on
the Windows domain, select Use Windows NT integrated security. Otherwise, select
Use a specific user name and password, and type them in the relevant boxes.
Select the database to which you are connecting (in this example, NORTHWIND).
To test the connection at this time, click Test Connection. This is an optional,
recommended step.
Do one of the following:
a. Select the Allow saving password check box.
b. On the All tab, change the value of the Persist Security Info property to True.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
9.
Databases and MapForce
373
Click OK.
Connecting to Microsoft SQL Server (ODBC)
To connect to SQL Server using ODBC:
1.
2.
3.
Start the database connection wizard.
Click ODBC Connections.
Select User DSN (or System DSN, if you have administrative privileges), and then click
Add
© 2017 Altova Gmb H
.
Altova MapForce 2017 Professional Edition
374
Data Sources and Targets
Databases and MapForce
4.
Select SQL Server (or SQL Server Native Client, if available), and then click User
DSN (or System DSN if you are creating a System DSN).
5.
Enter a name and description to identify this connection, and then select from the list the
SQL Server to which you are connecting (SQLSERV01 in this example).
6.
If the database server was configured to allow connections from users authenticated on
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
375
the Windows domain, select With Windows NT authentication. Otherwise, select With
SQL Server authentication... and type the user name and password in the relevant
boxes.
7.
8.
Select the name of the database to which you are connecting (in this example,
Northwind).
Click Finish.
Connecting to MySQL (ODBC)
This topic provides sample instructions for connecting to a MySQL database server from a
Windows machine through the ODBC driver. The MySQL ODBC driver is not available on
Windows, so it must be downloaded and installed separately. This example uses MySQL ODBC
driver version 5.3.4 downloaded from the official website (see also Database Drivers Overview ).
Prerequisites:
MySQL ODBC driver must be installed on your operating system (for installation
instructions, check the documentation supplied with the driver).
You have the following database connection details: host, database, port, username, and
password.
To connect to MySQL via ODBC:
1.
Start the database connection wizard.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
376
Data Sources and Targets
2.
Databases and MapForce
Select MySQL (ODBC), and then click Next.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
3.
4.
Databases and MapForce
377
Select Create a new Data Source Name (DSN) with the driver, and select a MySQL
driver. If no MySQL driver is available in the list, click Edit Drivers, and select any
available MySQL drivers (the list contains all ODBC drivers installed on your operating
system).
Click Connect.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
378
Data Sources and Targets
5.
6.
Note:
Databases and MapForce
In the Data Source Name box, enter a descriptive name that will help you identify this
ODBC data source in future.
Fill in the database connection credentials (TCP/IP Server, User, Password), select a
database, and then click OK.
If the database server is remote, it must be configured by the server administrator to
accept remote connections from your machine's IP address. Also, if you click Details>>,
there are several additional parameters available for configuration. Check the driver's
documentation before changing their default values.
Connecting to Oracle (ODBC)
This example illustrates a common scenario where you connect from MapForce to an Oracle
database server on a network machine, through an Oracle database client installed on the local
operating system.
The example includes instructions for setting up an ODBC data source (DSN) using the database
connection wizard in MapForce. If you have already created a DSN, or if you prefer to create it
directly from ODBC Data Source administrator in Windows, you can do so, and then select it
when prompted by the wizard. For more information about ODBC data sources, see Setting up an
ODBC Connection.
Prerequisites:
The Oracle database client (which includes the ODBC Oracle driver) must be installed
and configured on your operating system. For instructions on how to install and configure
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
379
an Oracle database client, refer to the documentation supplied with your Oracle software.
The tnsnames.ora file located in Oracle home directory contains an entry that describes
the database connection parameters, in a format similar to this:
ORCL =
(DESCRIPTION =
(ADDRESS_LIST =
(ADDRESS = (PROTOCOL = TCP)(HOST = server01)(PORT = 1521))
)
(CONNECT_DATA =
(SID = orcl)
(SERVER = DEDICATED)
)
)
The path to the tnsnames.ora file depends on the location where Oracle home directory
was installed. For Oracle database client 11.2.0, the default Oracle home directory path
could be as follows:
C:\app\username\product\11.2.0\client_1\network\admin\tnsnames.ora
You can add new entries to the tnsnames.ora file either by pasting the connection
details and saving the file, or by running the Oracle Net Configuration Assistant wizard (if
available).
To connect to Oracle using ODBC:
1.
Start the database connection wizard.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
380
Data Sources and Targets
2.
Select Oracle (ODBC / JDBC), and then click Next.
3.
Select ODBC.
Altova MapForce 2017 Professional Edition
Databases and MapForce
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
4.
Click Edit Drivers.
5.
Select the Oracle drivers you wish to use (in this example, Oracle in
OraClient11g_home1). The list displays the Oracle drivers available on your system
after installation of Oracle client.
© 2017 Altova Gmb H
381
Altova MapForce 2017 Professional Edition
382
Data Sources and Targets
6.
7.
Databases and MapForce
Click Back.
Select Create a new data source name (DSN) with the driver, and then select the
Oracle driver chosen in step 4.
Avoid using the Microsoft-supplied driver called Microsoft ODBC for Oracle driver.
Microsoft recommends using the ODBC driver provided by Oracle (see http://
msdn.microsoft.com/en-us/library/ms714756%28v=vs.85%29.aspx)
8.
Click Connect.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
383
9.
In the Data Source Name text box, enter a name to identify the data source (in this
example, Oracle DSN 1).
10. In the TNS Service Name box, enter the connection name as it is defined in the
tnsnames.ora file (see prerequisites). In this example, the connection name is ORCL.
11. Click OK.
12. Enter the username and password to the database, and then click OK.
Connecting to Oracle (JDBC)
This example shows you how to connect to an Oracle database server from a client machine,
using the JDBC interface. The connection is created as a pure Java connection, using the Oracle
Instant Client Package (Basic) available from the Oracle website. The advantage of this
connection type is that it requires only the Java environment and the .jar libraries supplied by the
Oracle Instant Client Package, saving you the effort to install and configure a more complex
database client.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
384
Data Sources and Targets
Databases and MapForce
Prerequisites:
Java Runtime Environment (JRE) or Java Development Kit (JDK) must be installed on your
operating system.
The operating system's PATH environment variable must include the path to the bin
directory of the JRE or JDK installation directory, for example C:\Program Files (x86)
\Java\jre1.8.0_51\bin.
The Oracle Instant Client Package (Basic) must be available on your operating
system. The package can be downloaded from the official Oracle website. This example
uses Oracle Instant Client Package version 12.1.0.2.0, for Windows 32-bit.
You have the following database connection details: host, port, service name, username,
and password.
To connect to Oracle through the Instant Client Package:
1.
2.
3.
4.
5.
Start the database connection wizard.
Click JDBC Connections.
Next to "Classpaths", enter the path to the .jar file which provides connectivity to the
database. If necessary, you can also enter a semicolon-separated list of .jar file paths. In
this example, the required .jar file is located at the following path: C:\jdbc
\instantclient_12_1\odbc7.jar. Note that you can leave the "Classpaths" text box empty
if you have added the .jar file path(s) to the CLASSPATH environment variable of the
operating system (see also Configuring the CLASSPATH).
In the "Driver" box, select either oracle.jdbc.OracleDriver or
oracle.jdbc.driver.OracleDriver. Note that these entries are available if a valid .jar file
path is found either in the "Classpath" text box, or in the operating system's
CLASSPATH environment variable (see the previous step).
Enter the username and password to the database in the corresponding text boxes.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
6.
Databases and MapForce
385
Enter the connection string to the database server in the Database URL text box, by
replacing the highlighted values with the ones applicable to your database server.
jdbc:oracle:thin:@//host:port:service
7.
Click Connect.
Connecting to PostgreSQL (ODBC)
This topic provides sample instructions for connecting to a PostgreSQL database server from a
Windows machine through the ODBC driver. The PostgreSQL ODBC driver is not available on
Windows, so it must be downloaded and installed separately. This example uses the psqlODBC
driver (version 09_03_300-1) downloaded from the official website (see also Database Drivers
Overview).
Note:
You can also connect to a PostgreSQL database server directly (without the ODBC
driver), see Setting up a PostgreSQL Connection.
Prerequisites:
psqlODBC driver must be installed on your operating system (for installation instructions,
check the documentation supplied with the driver).
You have the following database connection details: server, port, database, user name,
and password.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
386
Data Sources and Targets
Databases and MapForce
To connect to PostgreSQL using ODBC:
1.
Start the database connection wizard.
2.
Select PostgreSQL (ODBC), and then click Next.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
3.
4.
5.
Databases and MapForce
387
Select Create a new Data Source Name (DSN) with the driver, and select the
PostgreSQL driver. If no PostgreSQL driver is available in the list, click Edit Drivers, and
select any available PostgreSQL drivers (the list contains all ODBC drivers installed on
your operating system).
Click Connect.
Fill in the database connection credentials (Database, Server, Port, User Name,
Password), and then click OK.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
388
Data Sources and Targets
Databases and MapForce
Connecting to Progress OpenEdge (ODBC)
This topic provides sample instructions for connecting to a Progress OpenEdge database server
through the Progress OpenEdge 11.6 ODBC driver.
Prerequisites
The ODBC Connector for Progress OpenEdge driver must be installed on your operating
system. The Progress OpenEdge ODBC driver can be downloaded from the vendor's
website (see also Database Drivers Overview). Make sure to download the 32-bit driver
when running the 32-bit version of MapForce, and the 64-bit driver when running the 64-bit
version. After installation, check if the ODBC driver is available on your machine (see
also Viewing the Available ODBC Drivers).
You have the following database connection details: host name, port number, database
name, user ID, and password.
Connecting to Progress OpenEdge through ODBC
1.
2.
3.
Start the database connection wizard.
Click ODBC Connections.
Click User DSN (alternatively, click System DSN, or File DSN, in which case the
subsequent instructions will be similar).
4.
Click Add
.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
5.
Select the Progress OpenEdge Driver from the list, and click User DSN (or System
DSN, if applicable).
6.
Fill in the database connection credentials (Database, Server, Port, User Name,
Password), and then click OK. To verify connectivity before saving the entered data, click
Test Connect.
7.
Click OK. The new data source now appears in the list of ODBC data sources.
© 2017 Altova Gmb H
389
Altova MapForce 2017 Professional Edition
390
Data Sources and Targets
8.
Databases and MapForce
Click Connect.
Connecting to Progress OpenEdge (JDBC)
This topic provides sample instructions for connecting to a Progress OpenEdge 11.6 database
server through JDBC.
Prerequisites
Java Runtime Environment (JRE) or Java Development Kit (JDK) must be installed on your
operating system. Make sure that the platform of MapForce (32-bit, 64-bit) matches that
of the JRE/JDK.
The operating system's PATH environment variable must include the path to the bin
directory of the JRE or JDK installation directory, for example C:\Program Files (x86)
\Java\jre1.8.0_51\bin.
The Progress OpenEdge JDBC driver must be available on your operating system. In this
example, JDBC connectivity is provided by the openedge.jar and pool.jar driver
component files available in C:\Progress\OpenEdge\java as part of the OpenEdge SDK
installation.
You have the following database connection details: host, port, database name,
username, and password.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
391
Connecting to OpenEdge through JDBC
1.
2.
3.
4.
5.
6.
Start the database connection wizard.
Click JDBC Connections.
Next to "Classpaths", enter the path to the .jar file which provides connectivity to the
database. If necessary, you can also enter a semicolon-separated list of .jar file paths. In
this example, the required .jar file paths are: C:\Progress\OpenEdge\java
\openedge.jar;C:\Progress\OpenEdge\java\pool.jar;. Note that you can leave the
"Classpaths" text box empty if you have added the .jar file path(s) to the CLASSPATH
environment variable of the operating system (see also Configuring the CLASSPATH).
In the "Driver" box, select com.ddtek.jdbc.openedge.OpenEdgeDriver. Note that this
entry is available if a valid .jar file path is found either in the "Classpath" text box, or in the
operating system's CLASSPATH environment variable (see the previous step).
Enter the username and password to the database in the corresponding text boxes.
Enter the connection string to the database server in the Database URL text box, by
replacing the highlighted values with the ones applicable to your database server.
jdbc:datadirect:openedge://host:port;databaseName=db_name
7.
Click Connect.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
392
Data Sources and Targets
Databases and MapForce
Connecting to Sybase (JDBC)
This topic provides sample instructions for connecting to a Sybase database server through
JDBC.
Prerequisites:
Java Runtime Environment (JRE) must be installed on your operating system.
Sybase jConnect component must be installed on your operating system (in this
example, jConnect 7.0 is used, installed as part of the Sybase Adaptive Server
Enterprise PC Client installation). For the installation instructions of the database client,
refer to Sybase documentation.
You have the following database connection details: host, port, database name,
username, and password.
To connect to Sybase through JDBC:
1.
2.
3.
4.
Start the database connection wizard.
Click JDBC Connections.
Next to "Classpaths", enter the path to the .jar file which provides connectivity to the
database. If necessary, you can also enter a semicolon-separated list of .jar file paths. In
this example, the required .jar file path is: C:\sybase\jConnect-7_0\classes\jconn4.jar.
Note that you can leave the "Classpaths" text box empty if you have added the .jar file
path(s) to the CLASSPATH environment variable of the operating system (see also
Configuring the CLASSPATH).
In the "Driver" box, select com.sybase.jdbc4.jdbc.SybDriver. Note that this entry is
available if a valid .jar file path is found either in the "Classpath" text box, or in the
operating system's CLASSPATH environment variable (see the previous step).
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
5.
6.
Databases and MapForce
393
Enter the username and password to the database in the corresponding text boxes.
Enter the connection string to the database server in the Database URL text box, by
replacing the highlighted values with the ones applicable to your database server.
jdbc:sybase:Tds:hostName:port/databaseName
7.
7.2.1.11
Click Connect.
Database Connections on Linux and Mac
If you have licensed any of the following Altova server products—MobileTogether Server, MapForce
Server, or StyleVision Server, a common scenario is to design MobileTogether designs, MapForce
mappings, or StyleVision transformations on a Windows desktop machine, and then deploy them
to a server machine (either Windows, Linux, or Mac) to automate their execution.
In this documentation, the term "server execution files" is used to denote the following file types:
MapForce Server execution files (.mfx)
MobileTogether design files (.mtd)
StyleVision transformations (.sps) packaged as Portable XML Forms (.pxf).
The following scenarios are possible when deploying server execution files:
1.
"Design and execute on Windows". In this scenario, you design the MobileTogether
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
394
Data Sources and Targets
2.
Databases and MapForce
designs, MapForce mappings, or StyleVision transformations on Windows, and then run
their corresponding server execution files on a Windows system as well (which can either
be the same Windows machine, or a remote Windows server).
"Design on Windows, execute on Linux or Mac". In this scenario, you design all of
the above files on Windows, and then deploy their corresponding server execution files to
Linux and Mac for execution.
In the "Design and execute on Windows" scenario, the selection of available database
technologies and drivers comprises any of ADO, ODBC, JDBC, as well as SQLite
connections (see Database Drivers Overview).
In the "Design on Windows, execute on Linux or Mac" scenario, ADO and ODBC
connections are not supported. In this scenario, you can use direct SQLite connections (see
SQLite connections) and JDBC connections (see JDBC connections).
When you deploy server execution files to a server, databases are not included in the deployed
package (this also applies to file-based databases such as SQLite and Microsoft Access), so a
connection to them must be set up on the deployment server as well. In other words, the same
database configuration must be in place both on the operating system where you design and on
the server to which you deploy the files. An exception to this rule are native (not driver-based)
PostgreSQL connections. Native PostgreSQL connections do not require configuration outside
MapForce. For more information, see Setting up a PostgreSQL Connection.
In general, the scenario in which you deploy server execution files to a different operating system
is slightly more complex, since it requires that the same database configuration exist on both
machines. To bypass complexity while designing locally and deploying remotely, consider using
the Global Resources feature available in MapForce, MobileTogether Designer, and StyleVision.
For example, you can define two different Global Resource configurations to connect to the same
database: one which would specify the connection settings using the Windows-style path
conventions, and another one—using Linux-style path conventions. You could then use the first
connection to test your files during the design phase, and the second connection to run the
execution file on the Linux server.
SQLite connections on Linux and Mac
There is no need to separately install SQLite on Linux and Mac since support for it is integrated
into Altova server products as well. Therefore, if your server execution files include calls to a
SQLite database, you will be able to run them without having to install SQLite first. You need to
ensure, however, that the server execution files use the correct path to the database file on the
Linux or Mac machine. That is, before running the server execution files on the Linux or Mac
server, make sure that the SQLite database file is referenced through a path which is POSIX
(Portable Operating System Interface) compliant. This assumes that no Windows-style drive
letters are used in the path, and directories are delimited by the forward slash character ( / ). For
example, the path /usr/local/mydatabase.db is POSIX compliant, while the path c:\sqlite
\mydatabase.db isn't.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
395
JDBC connections on Linux and Mac
To set up a JDBC connection on Linux or Mac:
1.
2.
Note:
Download the JDBC driver supplied by the database vendor and install it on the operating
system. Make sure to select the 32-bit version if your operating system runs on 32-bit,
and the 64-bit version if your operating system runs on 64-bit.
Set the environment variables to the location where the JDBC driver is installed. Typically,
you will need to set the CLASSPATH variable, and possibly a few others. To find out
which specific environment variables must be configured, check the documentation
supplied with the JDBC driver.
On Mac OS, the system expects any installed JDBC libraries to be in the /Library/Java/
Extensions directory. Therefore, it is recommended that you unpack the JDBC driver to
this location; otherwise, you will need to configure the system to look for the JDBC library
at the path where you installed the JDBC driver.
Oracle Connections on Mac OS X Yosemite
On Mac OS X Yosemite, you can connect to an Oracle database through the Oracle Database
Instant Client. Note that, if you have a Mac OS with a Java version prior to Java 8, you can also
connect through the JDBC Thin for All Platforms library, in which case you may disregard the
instructions in this topic.
You can download the Oracle Instant Client from the Oracle official download page. Note that
there are several Instant Client packages available on the Oracle download page. Make sure to
select a package with Oracle Call Interface (OCI) support, (for example, Instant Client Basic).
Also, make sure to select the 32-bit version if your operating system runs on 32-bit, and the 64-bit
version if your operating system runs on 64-bit.
Once you have downloaded and unpacked the Oracle Instant Client, edit the property list (.plist)
file shipped with the installer so that the following environment variables point to the location of the
corresponding driver paths, for example:
Variable
Sample Value
CLASSPATH
/opt/oracle/instantclient_11_2/ojdbc6.jar:/opt/oracle/
instantclient_11_2/ojdbc5.jar
TNS_ADMIN
/opt/oracle/NETWORK_ADMIN
ORACLE_HOME
/opt/oracle/instantclient_11_2
DYLD_LIBRARY_PATH
/opt/oracle/instantclient_11_2
PATH
$PATH:/opt/oracle/instantclient_11_2
Note:
Edit the sample values above to fit the paths where Oracle Instant Client files are installed
on your operating system.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
396
7.2.2
Data Sources and Targets
Databases and MapForce
Introduction to Database Mappings
This section is an introduction to working with databases in MapForce. It shows you how to work
with a database after the connection to it is successfully established (see Connecting to a
Database). This includes selecting the database objects that you want to appear on the mapping,
handling database relationships, and configuring the database settings applicable to the mapping
process. Examples of how to achieve specific goals when mapping data to or from database
components are also included.
7.2.2.1
Adding Databases to the Mapping
Before adding a database to the mapping, make sure to select a transformation language where
database mappings are supported. This can be either the BUILT-IN transformation language, or
any of the following languages: C++, C#, Java (see also Selecting a Transformation Language).
Note that, if you intend to deploy the mapping to FlowForce Server or execute it with MapForce
Server, or use features such as Bulk Transfer and stored procedures, BUILT-IN must be selected
as transformation language.
Once the desired transformation language is selected, you can add a database to the mapping in
one of the following ways:
On the Insert menu, click Database.
Click the Insert Database (
) toolbar button.
When you take any of these actions, a database connection wizard appears, guiding you through
the steps required to connect to the database.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
397
Datab ase Connection Wizard
Note:
In some advanced scenarios, databases can also be added to the mapping as variables
(see Using Variables). When you choose to add a database structure as a variable, the
same database connection wizard mentioned above appears.
For instructions on how to proceed with this wizard so as to set up a connection to any of the
databases supported by MapForce, see Connecting to a Database and, in particular, the step-bystep examples, including:
Connecting to Firebird (ODBC)
Connecting to IBM DB2 (ODBC)
Connecting to an Existing Microsoft Access Database
Connecting to Microsoft SQL Server (ADO)
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
398
Data Sources and Targets
Databases and MapForce
Connecting to MySQL (ODBC)
Connecting to Oracle (ODBC)
Connecting to PostgreSQL (ODBC)
Connecting to Progress OpenEdge (JDBC)
Connecting to an Existing SQLite Database
Connecting to Sybase (JDBC)
Once the database connection is successfully established, you are prompted to select the
database objects that should appear on the mapping. See Adding, Editing, and Removing
Database Objects for further information.
7.2.2.2
Example: Adding the "altova.mdb" Database to the Mapping
This example shows you how to add a sample Microsoft Access database to a mapping. The
sample database is called altova.mdb and can be found in the <Documents>\Altova
\MapForce2017\MapForceExamples\ folder. The altova.mdb database supports various
database-related actions and concepts described in this documentation.
To add the altova.mdb database to the mapping:
1.
On the Insert menu, click Database. Alternatively, click the Insert Database (
toolbar button.
Altova MapForce 2017 Professional Edition
)
© 2017 Altova Gmb H
Data Sources and Targets
2.
Databases and MapForce
399
Click Microsoft Access (ADO), and then click Next.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
400
Data Sources and Targets
3.
4.
Databases and MapForce
Browse for the altova.mdb file available in the <Documents>\Altova\MapForce2017
\MapForceExamples\ folder, and then click Connect.
When prompted to select the database objects, select User Tables.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
7.2.2.3
Databases and MapForce
401
Adding, Editing, and Removing Database Objects
Some databases can have a large number of objects (such as schemas, tables, views, and so
on). This topic shows you how to get on the mapping only those database objects that are
required for mapping purposes. Below, we will be using a sample Access database; the
instructions are similar for other database types.
1.
2.
3.
On the Insert menu, click Database.
Click Connection Wizard, and then click Microsoft Access (ADO).
Click Next, and browse for the altova.mdb available in the <Documents>\Altova
\MapForce2017\MapForceExamples\ folder.
A dialog box appears, enabling you to select the database objects that you want to be included
into the mapping.
To include a database object (for example, a table) it in the mapping, click the check box next to
it. For the purpose of this example, click the check box next to User Tables.
The Object Locator button (
) allows you to find specific database items. Select a particular
object (or type its name) in the combo box which appears in the lower area of dialog box.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
402
Data Sources and Targets
Databases and MapForce
The Filter button (
) allows you to filter objects by name. Once you click the Filter button, a
filter icon is available next to objects which supports filtering (in this example, "Tables").
Click the filter icon to choose whether the object name should begin with, end with, be equal with,
or contain the search text.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
403
Now you can enter the search text next to the filter (in this example, "A"):
The Show checked objects only button (
active.
) displays those items where a check box is
The Add/Edit SELECT Statement button enables you to add or edit custom SELECT statements
for the current database. The data returned by such statements then becomes available as
mapping source. For more information, see SQL SELECT Statements as Virtual Tables.
The Add/Edit Relations button enables you to define local primary and foreign key relationships
between fields in the database, in addition to those that may already be present. For more
information, see Defining Local Relationships.
The Add/Edit Recordset Structures button applies for databases that support stored procedures.
It is only enabled if a stored procedure is currently selected from the database tree. For more
information, see Stored Procedures.
The Show Preview button enables you to quickly preview the data of the currently selected table
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
404
Data Sources and Targets
Databases and MapForce
or view. Note that you can also browse and query a database independently of the mapping
process, by using the Database Browser. For more information, see Browsing and Querying
Databases.
When you are ready to add the database objects to the mapping, click OK. Only the selected
tables, views, etc. will appear on the database component, and you can draw mapping
connections to or from them in the standard MapForce way.
To change at any time the database objects, right-click the component, and select Add/Remove/
Edit Database Objects.
7.2.2.4
Handling Database Relationships
Relational databases, as their name implies, normally have relationships defined between their
tables. Taking as example the altova.mdb database found in the folder <Documents>\Altova
\MapForce2017\MapForceExamples\Tutorial\, several relationships exist in it, for example:
The sample company (corresponding to the table "Altova") consists of one or more offices
(for example, in Brenton and in Vereno). In database terminology, there is a one-to-many
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
405
relationship between the "Altova" and "Office" tables. In other words, for each
PrimaryKey record in "Altova" table there can be multiple ForeignKey records in the
"Office" table. Any "Office" record where ForeignKey value corresponds to PrimaryKey
value in "Altova" should therefore be considered an office of "Altova".
Each office consists of one or several departments (for example, "Marketing", "IT",
"Development"). Again, there is a one-to-may relationship between "Office" and
"Department" tables.
Finally, each department consists of one or several people. Hence, the one-to-many
relationship between the "Department" and "Person" tables.
Tab le relationships in altova.mdb datab ase (Microsoft Access "Relationships" view)
Relationships between database tables are important for mapping purposes. MapForce keeps
track of such database relationships when you add a database to the mapping. This enables you
to preserve the database relationships when mapping data to or from a database. To understand
this concept better, add the altova.mdb database to the mapping (using the Insert | Database
menu command). Let us call each of the tables below a "root" table:
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
406
Data Sources and Targets
Databases and MapForce
"Root" tab les
Expanding a "root" table displays all related tables beneath it in a tree view. For example, if you
expand the Office table, notice how the related table hierarchy is displayed:
A left arrow (
) in front of a table denotes that this is a child table. For example,
Address is a child of Office. Department is also a child of Office, as well as a "sibling"
table of Address, so both have the same indentation level. As you can see, the
relationship on the mapping corresponds to the "Relationships" diagram above.
A right arrow (
) in front of a table denotes a parent table. For example, Altova is a
parent of Office.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
407
Tab les relationships in MapForce (altova.mdb datab ase)
This hierarchical representation of tables helps you preserve the existing database relationships
when your mapping reads from or writes to a database. For example, let's assume you want to
get all the records from the Person table into an XML file, grouped by their department.
Specifically, your XML file should link every person to a department, similar to the altova.mdb
database used in this example:
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
408
Data Sources and Targets
Databases and MapForce
As illustrated above, the "Administration" department has three people, "Marketing" has two
people, "Engineering" has six people, etc.
When mapping data from this database, if you want every person to be distributed to the correct
department, it is important that you use Department as "root" table, and then map from the
Person table which is child of Department:
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
409
The mapping above is a modified DB_Altova_Hierarchical.mfd from the <Documents>\Altova
\MapForce2017\MapForceExamples\ folder. When you preview the mapping, the result is that
each person is grouped by department, which was the intended behaviour. That is,
"Administration" has three people, "Marketing" has two people, "Engineering" has six people, etc.
Now have a look at the slightly modified mapping below, where connections have been
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
410
Data Sources and Targets
Databases and MapForce
deliberately drawn so that both Department and Person are "root" tables.
This time, when you preview the mapping, all persons (regardless of their source department) are
grouped under each target department, which was not the intended behaviour. That is,
"Administration" has 21 people, "Marketing" has 21 people, "Engineering" has 21 people, etc.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
411
In the second example, the database relationships are disregarded, due to the way the
connections were made.
Therefore, when you want to preserve database relationships, make sure that connections are
drawn to or from the same "root" table, which contains the child tables whose relationships you
want to preserve. This works in the same way for both source and target databases. For
examples of database mappings which preserve relationships, see the
DB_Altova_Hierarchical.mfd and Altova_Hierarchical_DB.mfd files available in the
<Documents>\Altova\MapForce2017\MapForceExamples\ folder (see also Inserting Data into
Multiple Linked Tables).
There might also be cases when you do not want to preserve database relationships. For
example, let's assume that you want to export all data from the altova.mdb database to a flat
XML file adhering to the SQL/XML specification (Part 14 of the Structured Query Language (SQL)
specification). This kind of mapping is illustrated by the DB_Altova_SQLXML.mfd sample,
available in the <Documents>\Altova\MapForce2017\MapForceExamples\ folder. The goal of
the mapping is to get database data as flat XML file. The target SQL/XML schema was generated
with XMLSpy, using the Convert | Create XML Schema from DB Structure menu command.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
412
Data Sources and Targets
Databases and MapForce
DB_Altova_SQLXML.mfd
As illustrated above, every database table has a corresponding element in the target XML. When
you preview the mapping result, you can see that the actual database rows from each table are
written to "row" elements in the target.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
413
As the XML output shows, no hierarchies exist between the XML elements; it is a flat SQL/XML
structure. The database relationships were ignored, because we intentionally mapped data from
multiple "root" tables.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
414
7.2.2.5
Data Sources and Targets
Databases and MapForce
Defining Local Relationships
When database tables do not have explicitly defined relationships between them, you can define
such relationships locally in MapForce. In particular, you can create, from MapForce, primary and
foreign key relationships between columns of different tables, without affecting the database in
any way. Any database columns can be used as primary or foreign keys. Also, new relations can
be created, in addition to those existing in the database. Locally defined relationships are saved
together with the mapping.
These "on-the-fly" relationships are called Local Relations in MapForce. Local relations can be
defined for the following database objects:
Database tables
Database views
Stored procedures and functions
User-defined SELECT statements
The altova-no-relation.mdb database used in this example is a simplified version of the
altova.mdb database supplied with MapForce. The "Person" and "Address" tables, as well as all
table relationships have been removed in Microsoft Access. As illustrated below, none of the
tables visible in the altova-no-relation tree have any child tables; all tables are on the same
"root" level. The content of each table is limited to the fields it contains.
Datab ase structure with no explicit relationships
The aim of the example is to display the offices of "Altova" and show the departments in each
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
415
office. Note that, in the altova-no-relation.mdb, the primary and foreign key relationships do not
exist explicitly, as mentioned above. They exist only logically (implicitly), so we will be re-creating
them locally in MapForce to achieve the goal of the mapping.
Local relations can be defined while adding a database to the mapping, or by right-clicking an
existing database component and selecting Add/Remove/Edit Database Objects from the
context menu, as illustrated in the steps below.
1.
2.
3.
4.
On the Insert menu, click Database.
In the connection wizard, click Microsoft Access (ADO), and then click Next.
Browse for the altova-no-relation.mdb database available in the <Documents>\Altova
\MapForce2017\MapForceExamples\Tutorial\ folder, and click Connect.
Select the User Tables check box.
5.
6.
Click the Add/Edit Relations button in the icon bar.
The "Add/Edit Table Relations" dialog box opens. Click Add Relation.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
416
Data Sources and Targets
Databases and MapForce
7.
Select values from the two drop-down lists so as to create a primary and foreign key
relationship between the "Altova" and "Office" tables, as illustrated below. The two dropdown lists allow you to select the tables or database objects you want to create relations
for. The left list specifies the object which stores the primary/unique key, while the right
one specifies the foreign key object. The Primary/Unique Key object will be the parent
object in MapForce, and the Foreign Key object will be shown as child in the database
component (see also Handling Database Relationships).
8.
Click OK to complete the local relation definition, and then click the Insert button to
insert the database into the mapping area.
At this stage, you have created a local relationship between the PrimaryKey column of the
"Altova" table and the ForeignKey column of the "Office" table. As illustrated below, the "Altova"
root table is now a parent to the "Office" table. Namely, the Office table is shown as a related
table below the Altova table with its own expand icon.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
417
However, the mapping goal is not yet complete. To complete the mapping goal, use the same
method to create a relationship between the Office and Department tables, as shown below.
To open again the "Add/Edit Relations" dialog box, right-click the database component, and
select Add/Remove/Edit Database Objects from the context menu.
Finally, add the target schema to the mapping as follows:
1.
2.
On the Insert menu, click Insert XML Schema/File.
Browse for the Altova_Hierarchical.xsd file available in the <Documents>\Altova
\MapForce2017\MapForceExamples\ folder. When prompted to supply a sample XML
file, click Skip. When prompted to select a root element, select "Altova".
Notice that, in order to preserve relationships between tables in the target XML, all connections
were drawn from the same "root" table, hierarchically (in this case, "Altova"). For more
information, see Handling Database Relationships.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
418
Data Sources and Targets
Databases and MapForce
Having defined the mapping as shown above, click the Output tab, to preview the result. The
mapping result shows the department elements nested under each respective office, which was
the intended goal of this mapping.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
7.2.2.6
Databases and MapForce
419
Executing Mappings Which Modify Databases
When a mapping modifies database data in any way (for example, by inserting, updating, or
deleting records), the changes are applied to the database by the engine that executes the
mapping. The engine that executes the mapping can be MapForce, MapForce Server (both
standalone or under FlowForce Server management), or the execution environment of the code
generated for C++, C#, or Java.
When you preview the mapping result directly in MapForce (by clicking the Output tab), an
update script is displayed. This script shows the SQL statements that are to be applied against
the database. The script is not actually executed against the database until you take this action
explicitly; it is available for preview only.
Output preview of a mapping which modifies a datab ase (Altova_Hierarchical_DB.mfd)
Note that this script must not be manually applied to the database using SQL tools other than the
execution engines mentioned above. The script may contain formatting of values not "understood"
by external SQL editors. Also, if multiple actions are defined against a table (for example, "Update
if... Insert Rest") only the first action is shown in the preview, since the second action is executed
conditionally.
If you want to apply the mapping changes to the database directly from MapForce, click the Run
SQL-Script command available in the Output menu. Remember that this action will actually
modify the database with immediate effect.
When the mapping is executed with MapForce Server (both standalone or under FlowForce Server
management), the changes to the database are applied with immediate effect. The same happens
in the generated code: the database changes are applied when you compile and run the code (for
example, by clicking the Run command in Visual Studio).
Your MapForce installation includes several example databases (Microsoft Access or SQLite
files) available in the <Documents>\Altova\MapForce2017\MapForceExamples\ folder. It
is advisable not to apply database changes from MapForce, using the Run SQL-Script
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
420
Data Sources and Targets
Databases and MapForce
command, against any of the example databases supplied with MapForce; this may render
the examples unusable. A simple way to avoid overriding original data is to back up the
entire <Documents>\Altova\MapForce2017\MapForceExamples\ folder before updating
any files in it.
For information about running mappings in execution environments other than MapForce, see:
Deploying Mappings to FlowForce Server
Compiling Mappings to MapForce Server Execution Files
Code Generator
7.2.2.7
Replacing Special Characters
When transforming database data, you might need to remove specific special characters, such as
the carriage return/line feed (CR/LF) characters, from the data source. This can be done with the
help of the MapForce library function char-from-code.
Consider a Microsoft Access database consisting of a table "Lines" which has two columns: "ID"
and "Description".
The goal is to extract each description to a CSV file (one description per line); therefore, a
mapping to achieve this goal could look as follows:
However, because each "Description" row in Access contains multiple lines separated by CR/LF
characters, the mapping output includes line breaks also, which is not the intended result:
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
421
To overcome this problem, we are going to add to the mapping the char-from-code and replace
functions from the MapForce built-in library (see also Working with Functions). Every description
must be processed so that, whenever the characters above are encountered, they should be
replaced by a space character.
In the Unicode chart (http://www.unicode.org/charts/), the LF and CR characters correspond to
hex 0A | dec 10 and hex 0D | dec 13 characters, respectively. Therefore, the mapping has to be
modified to convert the decimal Unicode values 13 and 10 to a string, so as to allow further
processing by the replace function.
If you preview the mapping now, notice that the CR/LF characters within each database field have
been replaced by a space.
7.2.2.8
Handling Null Values
To check at mapping runtime whether a database field is null, use the is-null and is-not-null
MapForce library functions. To see from MapForce if a table has null fields, query it using the
Database Browser (see Browsing and Querying Databases).
To set a database field to null, use the set-null function.
To replace null database values with a string, use the substitute-null function. A sample
mapping that illustrates this is DB_ApplicationList.mfd available in the <Documents>\Altova
\MapForce2017\MapForceExamples\ folder.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
422
Data Sources and Targets
Databases and MapForce
For information about handling NULL value comparisons in mappings which update databases,
see Handling Nulls in Database Table Actions.
For information about handling nulls when mapping database to or from XML documents, see Nil
Values / Nillable.
7.2.2.9
Generating Sequential and Unique Values
When inserting data or updating a database, sometimes you might need to create "on-the-fly"
sequential or unique values for those database fields which do not have any input from the
mapped source. For such cases, use the following built-in MapForce library functions:
auto-number (available in the "core | generator functions" library). This function is
generally used to generate primary key values for a numeric field.
create-guid (available in the "lang | generator functions" library). This function creates a
globally-unique identifier (as a hex-encoded string) for the specific field.
Note that values for database fields can also be written using database-generated values. This
option is available on the Database Table actions dialog box (see Database Table Actions
Settings) and is particularly useful when generating primary keys.
7.2.2.10
SQL Auto-Completion Suggestions
When you type SQL statements in certain contexts, MapForce may suggest text entries
automatically. Auto-completion is available in the following contexts:
SQL Editor (see Browsing and Querying Databases)
"Custom SQL" text box in the "Database Table Actions" dialog box (see Database Table
Actions Settings)
"Enter a SQL SELECT statement" dialog box (see Creating SELECT Statements)
Auto-completion
Use the Up and Down keyboard keys to navigate through the list of suggestions. To pick a
suggested entry, click it or press Enter.
To disable auto-completion suggestions:
1.
2.
3.
On the Tools menu, click Options (or press Ctrl+Alt+O).
Under Database, click SQL Editor.
Under Entry Helpers, clear the Automatically open check box.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
423
To invoke auto-completion suggestions manually as and when required:
Press Ctrl+Space.
7.2.2.11
Database Component Settings
After you add a database component to the mapping area, you can configure the settings
applicable to it from the Component Settings dialog box. You can open the Component settings
dialog box in one of the following ways:
Select the component, and then, on the Component menu, click Properties.
Double-click the component header.
Right-click the component, and then click Properties.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
424
Data Sources and Targets
Databases and MapForce
Datab ase Component Settings dialog b ox
The available settings are as follows.
Database
This group displays database connection information. Click Change to select a different
database, or to redefine the database objects in the existing database component. Connectors to
tables of the same name will be retained. You can also change the tables in the component, by
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
425
right clicking a database component and selecting Add/Remove/Edit Database Objects.
Data Source
Specifies the name of the current data source. For file-based
databases, this can be a path on the file system.
Connection Name
Specifies the name of the connection (this is the same as the
data source name if the database uses a data source)
Database Kind
Specifies the kind of the database.
Connection String
Displays the current database connection string. This readonly field is generated based on the information you supply
when creating or changing the database connection.
Login Settings
The login settings are used for all code generation targets and the built-in execution engine.
User
Enables you to change the user name for connecting to the
database. Mandatory if the database requires a user name to
connect.
Password
Enables you to change the password for connecting to the
database. Mandatory if the database requires a password to
connect.
JDBC-specific Settings
JDBC specific settings are only used for Java code generation.
JDBC Driver
Displays the currently active driver for the database
component. The default driver is automatically entered when
you define the database component. You can change the
driver entered here to suit your needs. Make sure that the
syntax of the entry in the Database URL field conforms to the
specific driver you choose.
Database URL
URL of the currently selected database. Make sure that this
entry conforms to the JDBC driver syntax, of the specific
driver entered in the JDBC-driver field.
ADO/OLEDB-specific Settings
ADO/OLEDB settings are only used for C++ and C# code generation. The Data Source and
Catalog settings are not used by the built-in execution engine.
Data Source
© 2017 Altova Gmb H
Displays the name of the ADO data source.
Altova MapForce 2017 Professional Edition
426
Data Sources and Targets
Databases and MapForce
Catalog
Displays the name of the ADO catalog.
Provider
Displays the currently active provider for the database
component.
Add. Options
Displays any additional database options.
Generation Settings
Generation settings apply to all code generation targets as well as the built-in execution engine.
Use transactions
Enables transaction processing when using a database as a
target. A dialog box opens when an error is encountered
allowing you to choose how to proceed. Transaction
processing is enabled for all tables of the database
component when you select this option. For more
information, see Using Transaction Rollback.
Strip schema names from table Allows you to strip database schema names from generated
names
code, only retaining the table names for added flexibility.
Note that this option only works for SQL Select statements
generated by MapForce. User-defined SQL-Statements,
when creating virtual tables, will not be modified.
Timeout for Statement Execution
When a database is used as a target component, execution timeouts can occur due to server
availability, traffic, long-running triggers, and other factors. This setting allows you to define how
long the timeout period can be before the database connection is closed. The setting takes effect
when querying database data as well as in generated C#, Java, and C++ code.
Timeout
Defines the time period, in seconds, that the execution
engine must wait for a database response before aborting the
execution of the database statement. The default setting for
the execution timeout is 60 seconds.
Infinite
When enabled, this option instructs the execution engine to
never time out.
Note:
7.2.3
Timeout for statement execution is not applicable to SQLite databases.
Mapping Data to Databases
This section provides instructions and examples for transferring data from any mapping source
supported by MapForce (for example, an XML file) to a target database. Use the following
roadmap for a summary of available options.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
I want to...
7.2.3.1
Databases and MapForce
427
Read this topic...
Insert data into a target database table based
on data supplied by the mapping...
Inserting Data into a Table
Control how primary key values are to be
created...
Inserting Data into a Table
Inserting Data into Multiple Linked Tables
Run a "preliminary" SQL statement to be
executed before a table is modified by the
mapping (for example, delete all records in the
table, or a custom SQL statement)...
Inserting Data into Multiple Linked Tables
Database Table Actions Settings
Preserve the hierarchical relationship of
records in tables linked by foreign keys...
Inserting Data into Multiple Linked Tables
Update a table conditionally...
Updating a Table
Merge records into a database table (update
some records, and also insert some other
records into the same table), based on a
condition...
"Update if... Insert Rest" Action
MERGE statements
Preserve database integrity when updating
tables that are linked to other tables through
foreign key relationships...
Options for Child Tables When Updating a
Parent Table
Define multiple actions against the same table
(for example, delete a record if a condition is
satisfied, otherwise insert a new record)...
"Delete if..." Action
"Ignore if..." Action
Preserve data integrity in case of failed
mapping execution...
Using Transaction Rollback
Insert multiple records into a database table in
bulk (combine multiple INSERT statements in
one query)...
Bulk Inserts (MapForce Server)
Avoid undesired results when mapping data to
target database tables that contain null
values...
Handling Nulls in Database Table Actions
Inserting Data into a Table
A mapping can insert data into a database table from any of the source components supported by
MapForce, including other databases. You can flexibly configure how the primary key of newly
inserted records should be created. For example, the primary key can be taken from the mapping,
generated by the database, or calculated based on existing key values in the database table.
This example shows you how to insert new records into an existing database table from an XML
file. You will also configure how the primary key is to be generated. The example uses the
following files:
altova-cmpy.xml — contains the source data to be inserted into the database.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
428
Data Sources and Targets
Databases and MapForce
Altova_Hierarchical.xsd — the schema used to validate the instance file above.
altova.mdb — the target database to be updated.
All files are available in the <Documents>\Altova\MapForce2017\MapForceExamples\ folder.
Below, the complete path to them will be omitted, for simplicity.
The mapping in this example modifies a sample database file. It is strongly recommended to
back up the original database and start with a new copy before following the steps below.
This ensures that the original examples are not overridden and that you get the same results
as below. For more information, see Executing Mappings Which Modify Databases.
The goal of the mapping is to insert companies found in the Altova-cmpy.xml as new records in
the "Altova" table of the altova.mdb database. If you open the source XML file, you will notice
that it contains only one company, called "Microtech OrgChart". Therefore, the mapping must add
a new record to the "Altova" table with the name "Microtech OrgChart". Also, a new primary key
must be generated for it.
To achieve the mapping goal, we will take the steps below.
Step 1: Insert the source XML component
On the Insert menu, click XML Schema/File, and browse for Altova_Hierarchical.xsd.
When prompted to supply an instance file, browse for Altova-cmpy.xml.
Step 2: Insert the target database
On the Insert menu, click Database, and go through the wizard steps to connect to
altova.mdb (see Example: Adding the "altova.mdb" Database to the Mapping).
Step 3: Draw the connections
Draw the mapping connections as shown below.
Note:
If unwanted connections are automatically drawn for descending items, the option "Autoconnect children" is active. In this case, to undo the last action, select the menu option
Edit | Undo. To disable the auto-connect option, select the menu option Connection |
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
429
Auto-connect matching children.
Step 4: Configure the Insert action
1.
On the target component, notice the Action: Insert (
) button. This button appears
for each table that has a connection from the mapping (in this case, the "Altova" table).
Click this button to configure in more detail the database action to be executed (in this
case, the insert action). The Database Table Actions dialog box appears.
2.
In the Database Table Actions dialog box, under Insert All, next to PrimaryKey, select
the max() + 1 option.
The options available in this list have the following meaning:
Option
Description
mapped value
Allows source data to be mapped to the database field
directly, and is the standard setting for all database fields. It is
also possible to use a stored procedure to supply a key value
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
430
Data Sources and Targets
Databases and MapForce
by defining a relation, see Using stored procedures to
generate primary keys.
max() + 1
Generates the key values based on the existing keys in the
database. For example, if the table has three records, with
primary keys 1, 2, and 3, then max() + 1 is 4.
In this example, the "Altova" table has only one record with
primary key 1, so max() + 1 is 2, which is the expected value
of the new primary key.
DB-generated
The database uses the Identity function to generate key
values.
The option mapped value next to "Name" signifies that this column will get the value
directly from the mapping. For reference to other options available on the Database Table
Actions dialog box, see Database Table Actions Settings.
Step 5: Preview the mapping and update the database
Click the Output tab to preview the mapping. A SQL script is generated, containing actions to be
executed against the database. The script has not modified the database yet; it is only for
preview.
To run the script against the database:
On the Output menu, click Run SQL-Script.
Note:
Running the SQL script directly from MapForce is just one of the ways to update the
database, see also Executing Mappings Which Modify Databases.
To see the result, open the altova.mdb database in DatabaseSpy or Access. Notice that a new
"Microtech OrgChart" record has been added to the "Altova" table with the new primary key 2. The
data for this record originated in the input XML instance.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
431
You have now finished creating a mapping which inserts data into a database table. For a
mapping example which inserts data both into the current table and a dependent child table, see
Inserting Data into Multiple Related Tables.
7.2.3.2
Inserting Data into Multiple Linked Tables
A database table may be a "parent" table; that is, it might be referred by other tables in the
database through foreign key relationships. In such scenarios, you can configure the mapping to
insert records not only into the parent table, but also into dependent child tables. For example,
when inserting a new "company" record into a database table, you can also insert records for
offices linked to this company, as well as their children departments, people, and so on.
This example shows you how to insert data into several tables while preserving the database
relationships. It is a slightly more elaborate version of the previous example, Inserting Data into a
Table. The example is accompanied by a sample mapping, and it uses the following files:
Altova_Hierarchical.mfd — the actual mapping file.
Altova_Hierarchical.xml — contains the source data to be inserted into the database.
Altova_Hierarchical.xsd — the schema used to validate the instance file above.
AltovaTarget.mdb — the target database to be updated.
All files are available in the <Documents>\Altova\MapForce2017\MapForceExamples\ folder.
Below, the complete path to them will be omitted, for simplicity.
The mapping in this example modifies a sample database file. It is strongly recommended to
back up the original database and start with a new copy before following the steps below.
This ensures that the original examples are not overridden and that you get the same results
as below. For more information, see Executing Mappings Which Modify Databases.
The goal of the mapping is to replace data in the target database (AltovaTarget.mdb) with data
from a source XML file. The XML file structure roughly corresponds to the hierarchical structure of
tables in the database. It is an organization chart, structured as follows: the top element is a
company which contains two offices. Each office contains departments, and each department
contains people. The same hierarchy exists in the AltovaTarget.mdb, where the "Altova" table
corresponds to the company. This table is linked, through a foreign key relationship, to records in
the "Office" table. Likewise, the "Office" links to "Department", and "Department" links to
"Person". To view a relationship diagram of the AltovaTarget.mdb database, open it in the
"Relationships" view of Access (see also Handling Database Relationships).
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
432
Data Sources and Targets
Databases and MapForce
To achieve the mapping goal, we will take the steps below.
Step 1: Insert the source XML component
On the Insert menu, click XML Schema/File, and browse for Altova_Hierarchical.xsd.
When prompted to supply an instance file, browse for Altova_Hierarchical.xml.
Step 2: Insert the target database
On the Insert menu, click Database, and go through the wizard steps to connect to
AltovaTarget.mdb. The instructions for connecting to this database are the same as for
altova.mdb (see Example: Adding the "altova.mdb" Database to the Mapping).
Step 3: Draw the connections
Draw the mapping connections as shown below. Notice that the primary and foreign keys
are not mapped; they will be generated on the fly, as shown below.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Note:
Databases and MapForce
433
If unwanted connections are automatically drawn for descending items, the option "Autoconnect children" is active. In this case, to undo the last action, select the menu option
Edit | Undo. To disable the auto-connect option, select the menu option Connection |
Auto-connect matching children.
Step 4: Configure the Insert actions
1.
On the target component, click the Action: Insert (
) button next to the "Altova"
table and configure the max() + 1 setting of the primary key as shown below. This setting
was explained in more detail in the previous example, see Inserting Data into a Table.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
434
Data Sources and Targets
Databases and MapForce
Also, notice that the DELETE all records option is enabled. This clears all existing
records from the table, before new ones are entered, which is the desired behavior in this
example. If you disable this option, new records (with a new primary key) will be added to
the database in addition to existing ones, every time you run the mapping, which is not
the desired behaviour.
For the scope of this example, the option also delete all records from child tables is
also enabled. This ensures that not only records from the "Altova" table are deleted, but
also all records in tables that are linked to "Altova" table through a foreign key
relationship. If the child tables have their own child tables, those will also be deleted, and
so on, down to the last table in the dependency tree. If you attempted to delete only
records from the root "Altova" table, this would violate the database integrity, and the
mapping execution would fail.
For reference to other options available on the Database Table Actions dialog box, see
Database Table Actions Settings.
2.
3.
Click OK to close the dialog box. Notice that, on the mapping area, the appearance of the
button has now changed to
. This indicates that a "Delete" statement is
configured to take place before the "Insert" action.
Click the
button next to the "Office" table and configure the max() + 1 setting of the
primary key.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
4.
Databases and MapForce
435
Perform step 3 for each table descending from "Office", namely: "Address",
"Department", and "Person". Make sure that all these tables are immediate descendants
of the root "Altova" table. For an explanation of what is a "root" table and why it is
necessary, see Handling Database Relationships.
Step 5: Preview the mapping and update the database
Click the Output tab to preview the mapping. A SQL script is generated, containing actions to be
executed against the database. The script has not modified the database yet; it is only for
preview.
To run the script against the database:
On the Output menu, click Run SQL-Script.
Note:
Running the SQL script directly from MapForce is just one of the ways to update the
database, see also Executing Mappings Which Modify Databases.
To see the result, open the "Altova" table in Microsoft Access, and observe how relationships from
the XML file have now been propagated to the database, from the "Altova" table down to the
"Person" table.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
436
Data Sources and Targets
Databases and MapForce
You have now finished creating a mapping which inserts data into multiple database tables, while
preserving the table integrity relationships.
7.2.3.3
Updating a Table
This example shows you how to update data of an existing database table with data coming from
an XML source. The example uses the following files:
altova-cmpy.xml — contains the source data to be inserted into the database.
Altova_Hierarchical.xsd — the schema used to validate the instance file above.
altova.mdb — the target database to be updated.
All files are available in the <Documents>\Altova\MapForce2017\MapForceExamples\ folder.
Below, the complete path to them will be omitted, for simplicity.
The mapping in this example modifies a sample database file. It is strongly recommended to
back up the original database and start with a new copy before following the steps below.
This ensures that the original examples are not overridden and that you get the same results
as below. For more information, see Executing Mappings Which Modify Databases.
The goal of the mapping is to update all records in "Person" table with instances of "Person" from
the XML document. Each person in the XML file has a PrimaryKey child element. Each person in
the "Person" table has a PrimaryKey column. Only those records where a person's PrimaryKey
in the XML file corresponds to a person's PrimaryKey in the database must be updated.
To achieve the mapping goal, we will take the steps below.
Step 1: Insert the source XML component
On the Insert menu, click XML Schema/File, and browse for Altova_Hierarchical.xsd.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
437
When prompted to supply an instance file, browse for altova-cmpy.xml.
Step 2: Insert the target database
On the Insert menu, click Database, and go through the wizard steps to connect to
altova.mdb (see Example: Adding the "altova.mdb" Database to the Mapping).
Step 3: Draw the connections
Draw the mapping connections as shown below.
Step 4: Configure the Update action
1.
2.
3.
On the target component, click the Action: Insert (
) button next to the "Person"
table.
Next to Action on record, select Update if... . This changes the database table action
to a conditional update action. That is, the current record will only be updated when a
condition is satisfied (see next step).
Next to PrimaryKey, select the value equal, as shown below. This defines the update
condition: that is, the database record will be updated only when its PrimaryKey value is
equal to the PrimaryKey value coming from the mapping.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
438
Data Sources and Targets
Databases and MapForce
In this example, the equality operator is applied to the PrimaryKey field, which is a likely
scenario when updating databases. Note that conditions can also be defined on other
fields which are not necessarily primary keys. For example, by selecting equal next to
the First and Last fields, you would update only those records where both the first and
last name is equal to that in the source XML.
4.
Click OK to close the dialog box. Notice that, back on the mapping, the Action: Insert
button has now changed to an Action: Update (
) button. This indicates that
an update action is configured to take place for this table.
Step 5: Preview the mapping and update the database
Click the Output tab to preview the mapping. A SQL script is generated, containing actions to be
executed against the database. The script has not modified the database yet; it is only for
preview.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
439
To run the script against the database:
On the Output menu, click Run SQL-Script.
Note:
7.2.3.4
Running the SQL script directly from MapForce is just one of the ways to update the
database, see also Executing Mappings Which Modify Databases.
"Update if... Insert Rest" Action
Sometimes, it is necessary not only to update existing records, but also to insert new records
into the same database table. For such cases, MapForce provides an "Update if... Insert Rest"
action. This works as follows:
If the Update if condition is true, then the existing database record is updated with data
from the mapping.
If the Update if condition is false, and an Insert Rest condition exists, then a new record
is inserted.
If records exist in the database with no counterpart in the source file, then these records
remain unchanged.
This example shows you to merge (both update and insert) data from an XML source into a
database table. The example uses the following files:
altova-cmpy-extra.xml — contains the source data to be inserted into the database.
Altova_Hierarchical.xsd — the schema used to validate the instance file above.
altova.mdb — the target database to be updated.
All files are available in the <Documents>\Altova\MapForce2017\MapForceExamples\ folder.
Below, the complete path to them will be omitted, for simplicity.
The mapping in this example modifies a sample database file. It is strongly recommended to
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
440
Data Sources and Targets
Databases and MapForce
back up the original database and start with a new copy before following the steps below.
This ensures that the original examples are not overridden and that you get the same results
as below. For more information, see Executing Mappings Which Modify Databases.
The goal of the mapping is to merge all records from a source XML document into a target
"Person" table. Namely, for each record in the source XML data, the mapping must do the
following:
If the person's PrimaryKey in the XML file corresponds to a person's PrimaryKey in the
database, then update the record.
Any existing records in the Person table which do not meet the above condition must not
be affected.
If the person's PrimaryKey in the XML file does not have a match in the target database
table, then add a new record to the database table.
To achieve the mapping goal, we will take the steps below.
Step 1: Insert the source XML component
On the Insert menu, click XML Schema/File, and browse for Altova_Hierarchical.xsd.
When prompted to supply an instance file, browse for altova-cmpy-extra.xml.
Step 2: Insert the target database
On the Insert menu, click Database, and go through the wizard steps to connect to
altova.mdb (see Example: Adding the "altova.mdb" Database to the Mapping).
Step 3: Draw the connections
Draw the mapping connections as shown below.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
441
Step 4: Configure the "Update if... Insert Rest" actions
1.
2.
3.
On the target component, click the Action: Insert (
) button next to the "Person"
table.
Next to Action on record, select Update if... . This changes the database table action
to a conditional update action. That is, the current record will only be updated when a
condition is satisfied (see next step).
Next to PrimaryKey, select the value equal, as shown below. This defines the update
condition: that is, the database record will be updated only when its PrimaryKey value is
equal to the PrimaryKey value coming from the mapping.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
442
Data Sources and Targets
4.
Databases and MapForce
Click Append Action. This adds a new action to the right of the existing Update If
action. Configure the new action as Insert Rest:
In the image above, the database table actions have been configured in accordance with
the goals of the mapping. That is, only when the Update If... condition is satisfied will the
record be updated; otherwise, it will be inserted. The option "mapped value" specifies that
values from the mapping will be used to populate all fields of the record.
It is also possible to define more than two actions against the same database table (this
is not necessary in this example, however). At mapping runtime, actions are executed
from left to right. The last Insert action is considered final; any other actions added after it
will be ignored.
Note that the Append Action button on the dialog box adds the new action after the
selected one. Insert Action adds the new action before the selected one. To delete an
existing action, click anywhere inside it, and then click Delete Action.
5.
Click OK to close the dialog box. Notice that, back on the mapping, the Action: Insert
button has now changed to an Action: Update; Insert (
) button. This
indicates that both an update and an insert action is configured to take place for this
table.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
443
Step 5: Preview the mapping and update the database
Click the Output tab to preview the mapping. A SQL script is generated, containing actions to be
executed against the database. The script has not modified the database yet; it is only for
preview.
SQL script (partial view) b efore updating the datab ase
You may notice that no INSERT statements are visible in the preview script. This is normal
behavior, because records are inserted conditionally, and the INSERT statements depend on the
result of the Update If action (which is not known before the mapping runs).
Note: For certain database types, MapForce creates MERGE statements instead of UPDATE
statements. For further information, see MERGE statements.
To run the script against the database:
On the Output menu, click Run SQL-Script.
Now that the mapping has been executed and the script applied against the database, notice that
INSERT statements are visible in the Output tab.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
444
Data Sources and Targets
Databases and MapForce
SQL script (partial view) after updating the datab ase
Note:
Running the SQL script directly from MapForce is just one of the ways to update the
database, see also Executing Mappings Which Modify Databases.
If you open the "Person" table in the DB query tab of MapForce (see Browsing and Querying
Databases), you can see the result of the mapping as follows:
All database records which had corresponding primary keys in the XML file have been
updated. Examples are records with primary key 1, 2, 3, 4, and 5.
All database records which had no corresponding keys in the XML file remained
unaffected. Examples are records with primary key 6, 7, 8, and 9.
New records have been inserted to the "Person" table (where key did not already exist in
the database). Examples are records with primary key 30 and 31.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
445
The "Person" tab le after updating the datab ase
7.2.3.5
MERGE Statements
For certain mappings which both update and insert data into a database table (see also "Update
if... Insert Rest" Action), MapForce generates MERGE statements to be executed against the
database at mapping runtime. The execution engine may not necessarily be MapForce, see
Executing Mappings Which Modify Databases.
MERGE statements are supported for the following database types:
SQL Server 2008 and later
Oracle
DB2
Firebird
MERGE statements reduce the number of database server calls, since they combine the INSERT
and UPDATE statements into one. Also, in case of MERGE statements, the consistency check
is done by the database. Note that MapForce creates MERGE statements automatically when it
detects a supported database type; it is not possible to manually influence whether MapForce
should create a MERGE statement.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
446
Data Sources and Targets
Databases and MapForce
To see whether the mapping will execute database MERGE statements at runtime (as opposed to
applying a combination of INSERT and UPDATE statements):
1.
2.
Create a mapping which uses an Update if... as well as an Insert Rest action. For an
example, see "Update if... Insert Rest" Action.
Preview the mapping, by clicking the Output tab.
If MERGE is supported by the database type, the generated SQL script includes MERGE
statements, for example:
If MERGE is not supported by the database type, the generated SQL script includes UPDATE
statements only. No INSERT statements are visible for preview, since those are to be executed
only if the Update If... condition is not satisfied (and this is not known before the mapping
execution).
Limitations:
With MERGE statements, the "Bulk Transfer" option (see Bulk Inserts (MapForce Server)
is supported only for ODBC and JDBC database connections.
7.2.3.6
Options for Child Tables When Updating a Parent Table
When the mapping updates a table which is a "parent" table (that is, it has foreign key
relationships to other tables), you can configure how the dependent records should be treated
both in the source data and in the target table. For example, let's assume that you want to update
the "Department" table in the altova.mdb database. Because every person is linked to a
department by means of a foreign key, you will likely want to take action against the "Person"
table as well (which could be an insert, update, or delete). Doing so would help you maintain the
database integrity and avoid mapping errors.
This topic discusses the options available for the "Person" table when you update the parent
"Department" table. It makes use of the following example files:
altova-cmpy-extra.xml — contains the source data to be inserted into the database.
Altova_Hierarchical.xsd — the schema used to validate the instance file above.
altova.mdb — the target database to be updated.
All files are available in the <Documents>\Altova\MapForce2017\MapForceExamples\ folder.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
447
Below, the complete path to them will be omitted, for simplicity.
The mapping in this example modifies a sample database file. It is strongly recommended to
back up the original database and start with a new copy before following the steps below.
This ensures that the original examples are not overridden and that you get the same results
as below. For more information, see Executing Mappings Which Modify Databases.
First, add the source XML schema and instance as well as the target database to the mapping
(see Example: Adding the "altova.mdb" Database to the Mapping). Follow the same steps as in
"Update if... Insert Rest" Action. Secondly, draw the mapping connections as shown below:
As illustrated above, the mapping updates the "Department" table in the target database. The
"Department" table is chosen as "root" table. For more information about what a root table is and
why it is necessary, see Handling Database Relationships. The action to be taken against the
child "Person" table is the subject of this topic.
The following tables illustrate various configuration options and the corresponding mapping result.
These options can be selected from the Database Table Actions dialog box of the parent
"Department" table and the child "Person" table.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
448
Data Sources and Targets
Databases and MapForce
Configuration A
Settings
"Department" tab le
Mapping result
Updates Department records where
PrimaryKey in the source XML corresponds
to the PrimaryKey in the database table.
Does not update existing Department
records which do not have a counterpart in
the input XML file (no such key exists in the
source).
Inserts, from the input XML instance, all
Person records that do not already exist in
the database.
Deletes child data (Person records) of those
Department records which satisfy the
Update if... condition.
"Person" tab le
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
449
Configuration B
Settings
Mapping result
The mapping fails with an SQL execution
error. The reason is that the mapping attempts
to insert new Person records with the same
primary key as the existing Person records. If
you want to insert records from the input XML
in addition to those already in the database,
see the next option.
"Department" tab le
"Person" tab le
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
450
Data Sources and Targets
Databases and MapForce
Configuration C
Settings
"Department" tab le
Mapping result
Updates Department records where
PrimaryKey in the source XML corresponds
to the PrimaryKey in the database table.
Does not update existing Department
records which do not have a counterpart in
the input XML file (no such key exists in the
source).
New Person records (with generated primary
keys) are inserted into the Person table in
addition to existing ones.
"Person" tab le
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
451
Configuration D
Settings
"Department" tab le
Mapping result
Updates Department records where
PrimaryKey in the source XML corresponds
to the PrimaryKey in the database table.
Does not update existing Department
records which do not have a counterpart in
the input XML file (no such key exists in the
source).
No records are inserted in the Person table
because the option Ignore input child
data is enabled for the parent Departments
table.
"Person" tab le
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
452
Data Sources and Targets
Databases and MapForce
Configuration E
Settings
"Department" tab le
Mapping result
Updates Department records where
PrimaryKey in the source XML corresponds
to the PrimaryKey in the database table.
Does not update existing Department
records which do not have a counterpart in
the input XML file (no such key exists in the
source).
Deletes all Person records linked to a
Department which has a corresponding
PrimaryKey in the source XML. The reason
is that the Delete data in child tables
option is enabled for the parent Department
table.
Person records linked to a department that
did not meet the Update if... condition
remain in the database.
No records in the Person table are updated.
"Person" tab le
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
453
Configuration F
Settings
"Department" tab le
Mapping result
Updates Department records where
PrimaryKey in the source XML corresponds
to the PrimaryKey in the database table.
Does not update existing Department
records which do not have a counterpart in
the input XML file (no such key exists in the
source).
Deletes all Person records linked to a
Department which has a corresponding
PrimaryKey in the source XML. The reason
is that the Delete data in child tables
option is enabled for the parent Department
table.
Person records linked to a department that
did not meet the Update if... condition
remain in the database.
"Person" tab le
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
454
Data Sources and Targets
Databases and MapForce
Configuration G
Settings
"Department" tab le
Mapping result
Updates Department records where
PrimaryKey in the source XML corresponds
to the PrimaryKey in the database table.
Does not update existing Department
records which do not have a counterpart in
the input XML file (no such key exists in the
source).
Deletes all Person records which satisfy
both of the following conditions:
a. The Person record is linked to a
Department which has a corresponding
PrimaryKey in the source XML, and
b. The Person record has a corresponding
PrimaryKey in the source XML.
"Person" tab le
7.2.3.7
"Delete if..." Action
The table action Delete if... is used to delete data from a database table conditionally. You can
define this action from the Database Table Actions dialog box (see Database Table Actions
Settings). For example, when mapping data from a source XML to a target database, you can
configure a Delete if... condition to check whether a certain field in the source XML is equal to a
field in the target database record (typically, a primary key value). If the Delete if... condition is
true (that is, the two fields are equal), the database record will be deleted when the mapping runs.
Note:
The Delete if... table action should not be confused with the Delete data in child
tables option available in the Database Table Actions dialog box. The Delete if... table
action only affects the table for which the action is defined; no other tables are affected.
This example shows you how to delete data from a database table conditionally, and also insert
records into the same database table based on the outcome of the delete condition.
This example uses the following files:
altova-cmpy-extra.xml — contains the source data to be inserted into the database.
Altova_Hierarchical.xsd — the schema used to validate the instance file above.
altova.mdb — the target database to be updated.
All files are available in the <Documents>\Altova\MapForce2017\MapForceExamples\ folder.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
455
Below, the complete path to them will be omitted, for simplicity.
The mapping in this example modifies a sample database file. It is strongly recommended to
back up the original database and start with a new copy before following the steps below.
This ensures that the original examples are not overridden and that you get the same results
as below. For more information, see Executing Mappings Which Modify Databases.
The goal of the mapping is as follows:
If any person records with the same PrimaryKey exist both in the source XML and the
target Person table, they must be deleted from the Person table.
All other records from the source XML must be inserted into the Person table.
To achieve the mapping goal, we will take the steps below.
Step 1: Insert the source XML component
On the Insert menu, click XML Schema/File, and browse for Altova_Hierarchical.xsd.
When prompted to supply an instance file, browse for altova-cmpy-extra.xml.
Step 2: Insert the target database
On the Insert menu, click Database, and go through the wizard steps to connect to
altova.mdb (see Example: Adding the "altova.mdb" Database to the Mapping).
Step 3: Draw the connections
Draw the mapping connections as shown below.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
456
Data Sources and Targets
Databases and MapForce
Step 4: Configure the "Delete if... Insert Rest" actions
1.
2.
3.
On the target component, click the Action: Insert (
) button next to the "Person"
table.
Next to Action on record, select Delete if... . This changes the database table action to
a conditional delete action. That is, the current record will only be deleted when a
condition is satisfied (see next step).
Next to PrimaryKey, select the value equal, as shown below. This defines the update
condition: that is, the database record will be deleted only when its PrimaryKey value is
equal to the PrimaryKey value coming from the mapping.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
4.
Databases and MapForce
457
Click Append Action. This adds a new action to the right of the existing Delete If
action. Configure the new action as Insert Rest:
In the image above, the database table actions have been configured in accordance with
the goals of the mapping. That is, only when the Delete If... condition is satisfied will the
record be deleted; otherwise, it will be inserted. The option "mapped value" specifies that
values from the mapping will be used to populate all fields of the record.
5.
Click OK to close the dialog box. Notice that, back on the mapping, the Action: Insert
button has now changed to an Action: Delete; Insert (
) button. This
indicates that both a delete and an insert action is configured for this table.
Step 5: Preview the mapping and update the database
Click the Output tab to preview the mapping. A SQL script is generated, containing actions to be
executed against the database. The script has not modified the database yet; it is only for
preview. To run the script against the database:
On the Output menu, click Run SQL-Script.
Note:
Running the SQL script directly from MapForce is just one of the ways to update the
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
458
Data Sources and Targets
Databases and MapForce
database, see also Executing Mappings Which Modify Databases.
If you open the "Person" table in the DB query tab of MapForce (see Browsing and Querying
Databases), you can see the result of the mapping as follows:
All database records which had corresponding primary keys in the XML file have been
deleted. Examples are records with primary key 1, 2, 3, 4, and 5.
All database records which had no corresponding keys in the XML file remained
unaffected. Examples are records with primary key 6, 7, 8, 9, 10, 11, 12, and 13.
New records have been inserted to the "Person" table (where key did not already exist in
the database). Examples are records with primary key 30 and 31.
The "Person" tab le after updating the datab ase
7.2.3.8
"Ignore if..." Action
The table action Ignore if... is used to prevent certain records in a database table from being
updated, based on a defined condition. The Ignore if... action is only meaningful when used in
combination with another database table action (such as the Insert Rest action). For example,
when mapping data from a source XML to a target database, you can configure an Ignore if...
condition to check whether a certain field in the source XML is equal to a field in the target
database record (typically, a primary key value). If the Ignore if... condition is true (that is, the
two fields are equal), the database record will be ignored when the mapping runs, and the next
defined action (Insert Rest, for example) will be executed.
This example shows you how insert records into a database table based on the outcome of the
Ignore if... condition. It uses the following files:
altova-cmpy-extra.xml — contains the source data to be inserted into the database.
Altova_Hierarchical.xsd — the schema used to validate the instance file above.
altova.mdb — the target database to be updated.
All files are available in the <Documents>\Altova\MapForce2017\MapForceExamples\ folder.
Below, the complete path to them will be omitted, for simplicity.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
459
The mapping in this example modifies a sample database file. It is strongly recommended to
back up the original database and start with a new copy before following the steps below.
This ensures that the original examples are not overridden and that you get the same results
as below. For more information, see Executing Mappings Which Modify Databases.
The goal of the mapping is as follows:
If any person records with the same PrimaryKey exist both in the source XML and the
target Person table, no action must be taken against them (that is, they must be
ignored).
If any person records which do not meet the above condition exist in the Person table, no
action must be taken against them either.
Records from the source XML which do not have a counterpart (no primary key) in the
Person table must be treated as new and inserted into the Person table with a new
primary key.
To achieve the mapping goal, we will take the steps below.
Step 1: Insert the source XML component
On the Insert menu, click XML Schema/File, and browse for Altova_Hierarchical.xsd.
When prompted to supply an instance file, browse for altova-cmpy-extra.xml.
Step 2: Insert the target database
On the Insert menu, click Database, and go through the wizard steps to connect to
altova.mdb (see Example: Adding the "altova.mdb" Database to the Mapping).
Step 3: Draw the connections
Draw the mapping connections as shown below.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
460
Data Sources and Targets
Databases and MapForce
Step 4: Configure the "Ignore if... Insert Rest" actions
1.
2.
3.
On the target component, click the Action: Insert (
) button next to the "Person"
table.
Next to Action on record, select Ignore if... . This changes the database table action to
a conditional ignore action. That is, the current record will only be ignored when a
condition is satisfied (see next step).
Next to PrimaryKey, select the value equal, as shown below. This defines the ignore
condition: that is, the database record will be ignored only when its PrimaryKey value is
equal to the PrimaryKey value coming from the mapping.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
4.
Databases and MapForce
461
Click Append Action. This adds a new action to the right of the existing Ignore If
action. Configure the new action as Insert Rest, with the primary key set to max() + 1,
as shown below:
In the image above, the database table actions have been configured in accordance with
the goals of the mapping. That is, only when the Ignore If... condition is satisfied will the
record be skipped; otherwise, it will be inserted. The option "mapped value" specifies that
values from the mapping will be used to populate all fields of the record. The option max()
+ 1 generates a unique, new primary key value for the record.
5.
Click OK to close the dialog box. Notice that, back on the mapping, the Action: Insert
button has now changed to an Action: Ignore; Insert ( ) button. This indicates that
both the ignore and insert actions are configured for this table.
Step 5: Preview the mapping and update the database
Click the Output tab to preview the mapping. A SQL script is generated, containing actions to be
executed against the database. The script has not modified the database yet; it is only for
preview. To run the script against the database:
On the Output menu, click Run SQL-Script.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
462
Data Sources and Targets
Note:
Databases and MapForce
Running the SQL script directly from MapForce is just one of the ways to update the
database, see also Executing Mappings Which Modify Databases.
If you open the "Person" table in the DB query tab of MapForce (see Browsing and Querying
Databases), you can see the result of the mapping as follows:
All database records which had corresponding primary keys in the XML file satisfied the
Ignore if... and remained unaffected. Examples are records with primary key 1, 2, 3, 4,
and 5.
All database records which had no corresponding keys in the XML file did not satisfy the
Ignore if... condition but nevertheless remained unaffected. Examples are records with
primary key 6, 7, 8, 9, 10, 11, 12, and 13.
New records have been inserted to the "Person" table (where key did not already exist in
the database). Examples are records with primary key 30 and 31 in the source XML file.
These were inserted into the database with the new primary key 22 and 23, respectively.
The "Person" tab le after updating the datab ase
7.2.3.9
Using Transaction Rollback
Transaction rollback is a feature that enables you to decide what should happen when a database
exception occurs for whatever reason. Namely, when you attempt to run a SQL script from
MapForce, and an error occurs, a dialog box such as the one below opens, prompting you to
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
463
choose how to continue. Because there might be SQL statements (transactions) that were
already executed successfully before the exception occurred, you can choose to roll back (undo)
all previously executed transactions, or only the current one.
Datab ase Transaction Exception dialog b ox
To be able to roll back unsuccessful database actions, you must enable transactions first. You
can enable database transactions as follows:
At database level. To enable transactions at database level, select the Use transactions
check box from the Database Component Settings dialog box (see also Database
Component Settings).
For each individual table. To enable transactions for each individual table, select the Use
transactions check box from the Database Table Actions dialog box (see also Database
Table Actions Settings).
You can enable transactions at database level without enabling them at table level, and vice versa.
Be aware that, when a database exception occurs, the available rollback options depend on how
transactions were enabled:
If transactions were not enabled at all, and an error occurs, execution stops at the point
the error occurs. All previously successful SQL statements are executed and the results
are stored in the database. It is not possible to roll back any transactions.
If transactions were enabled at table level but not at database level, execution stops at
the point the error occurs. In this case, the option Rollback all and stop is disabled.
You can roll back only the current transaction for that specific table, and either continue
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
464
Data Sources and Targets
Databases and MapForce
with the mapping execution or stop running the mapping completely.
If transactions were enabled at the database level only, execution stops at the point the
error occurs. All previously successful SQL statements are rolled back. No changes are
made to the database.
If transactions were enabled at both the database level and table level, execution stops at
the point the error occurs. In this case, select Rollback all and stop to roll back all
previously successful SQL statements for the entire database. To roll back only the last
transaction, and continue executing the mapping, select Rollback this transaction and
continue.
Note that the Database Transaction Exception dialog box is displayed only when you run the
mapping directly from MapForce, using the SQL | Run SQL-Script menu command. When the
mapping is executed in another environment (either by the generated code, or by MapForce
Server), and an error is encountered, an automatic rollback of the erroneous transaction occurs. In
this case, any successful SQL statements that were previously executed are rolled back only if
you enabled transactions at the database level, as explained above.
If you click Cancel on the dialog box, the execution rolls back the current SQL statement and
stops.
7.2.3.10
Bulk Inserts (MapForce Server)
The Use Bulk Transfer option allows you to insert data at very high speed from a MapForce
component (TXT, CSV, DAT, etc.) into a database table. Using this option dramatically speeds up
the Insert process, as only one statement needs to be executed instead of many.
Bulk transfer is supported when the following conditions are true:
The mapping transformation language is set to BUILT-IN. For further information, see
Selecting a Transformation Language.
The mapping is run by MapForce Server (either standalone or under FlowForce Server
management). This means that the mapping must be either compiled to .mfx format or
deployed to FlowForce Server. For further information, see Compiling Mappings to
MapForce Server Execution Files and Deploying Mappings to FlowForce Server.
The MapForce Server license is not limited to "single thread execution" on a multi-core
machine. That is, the Limit to single thread execution check box in the "Server
Management" tab of Altova LicenseServer must be inactive.
The database action is "Insert all"
The table into which the data is to be bulk loaded must be a "leaf" table, that is, on the
lowest hierarchy of the database. There should not be any related tables, views, or stored
procedures referencing the table in the mapping.
The database driver supports bulk insert on WHERE conditions.
Note:
If you are connecting to Microsoft Access and MySQL through ODBC, bulk inserts are
not supported by the ODBC driver.
This example shows you how create a mapping which bulk loads data from a sample source.txt
file into a target database. The example uses SQL Server 2014 and the AdventureWorks 2014
database. The latter can be downloaded from the CodePlex website (https://
msftdbprodsamples.codeplex.com/).
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Location
Location
Location
Location
Location
Databases and MapForce
465
A,15.3,39
B,46,34
C,56.33,0
D,0,399
E,0,97.43
source.txt
To define a bulk insert:
1.
2.
Set the transformation language to BUILT-IN (
).
Connect to the AdventureWorks 2014 database and add the "Production.Location" table
to the mapping. For more information, see Adding Databases to the Mapping.
3.
On the Insert menu, click Text, and add a source text file (such as the source.txt
sample above) to the mapping. For more information, see CSV and Text Files. Make sure
that the data types of both the source and the target components are identical. Data
types are visible on component when the Show Data Types (
be enabled.
) toolbar button must
4.
Draw the mapping connections as shown below. Note that the Database Actions button
is now visible to the right of the table name.
5.
Click the Database Actions button (
and click OK to confirm.
© 2017 Altova Gmb H
), select the Use Bulk Transfer check box,
Altova MapForce 2017 Professional Edition
466
Data Sources and Targets
Databases and MapForce
In the dialog box above, notice that the "Action on record" is "Insert All". The Batch size field
defines the number of records to be inserted per action.
Note:
When the Use Bulk Transfer option is enabled, the Use Transactions option becomes
disabled, and vice versa. If you want to enable transaction processing, click to clear the
Use Bulk Transfer check box.
Now that bulk insert is enabled, the next step is to execute the mapping in MapForce Server
(either standalone or under FlowForce Server management). For further information, see Compiling
Mappings to MapForce Server Execution Files and Deploying Mappings to FlowForce Server.
7.2.3.11
Handling Nulls in Database Table Actions
When a mapping updates a target database by means of table actions such as "Ignore If",
"Update If", "Delete If", MapForce compares the source data against the target data and
generates internal database update queries as a result. (These internal queries are available for
preview in the Output pane of MapForce, see Executing Mappings Which Modify Databases). The
generated queries reflect the comparison conditions that were defined from the "Database Table
Actions" dialog box (see also Database Table Actions Settings).
Null comparisons are a complex subject in the context of SQL and databases, in the sense that
there is no commonly accepted way to compare null values across various database types. From
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
467
a MapForce perspective, it is possible to configure a database mapping so that data comparison
is done in a NULL-aware manner, according to rules applicable to the database kind involved in
the mapping. "NULL-awareness" means that any NULL values will be treated as such for the
scope of data comparison (otherwise, you may get undesired results from the mapping). NULLawareness should be enabled if:
1.
2.
3.
The "Database Table Actions" dialog box contains "Ignore if", "Update if", "Delete if"
actions, and
These actions are taken against records that may contain NULL values, and
NULL values in the source table must be treated as equal with NULL values in the target
table.
By default, NULL-awareness is disabled. If the conditions above are true and NULL-awareness is
disabled, there may be instances where the target database table is not updated as expected (for
example, more rows are inserted or updated than necessary). This happens because NULL values
affect the data comparison and could produce undesired results. To prevent this from happening,
select the check box next to each nullable field (email, in the image below) from the "Database
Table Actions" dialog box. Be aware that the check box can be selected only for fields which are
nullable, and when at least one table action has an "equal" or "equal (ignore case)" condition.
Datab ase Tab le Actions dialog b ox
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
468
Data Sources and Targets
Databases and MapForce
Example
To better understand NULL awareness in mappings, let's analyze an example where comparison
of null data occurs. This example uses a Microsoft SQL Server database; however, it is also
applicable for any other supported database type. Optionally, if you have Microsoft SQL Server,
you can create the tables and data used in this example by running the following database script:
<Documents>\Altova\MapForce2017\MapForceExamples\Tutorial
\CreateNullableFields.sql.
For convenience, the database tables are illustrated below. Both tables store people data and
have the same columns. Also, the column email can contain null data in both tables.
+----+-----------+-----------+--------------------------+
| id | firstname | lastname | email
|
+----+-----------+-----------+--------------------------+
| 1 | Toby
| Hughey
| t.hughey@nanonull.com
|
| 2 | Mia
| Dahill
| NULL
|
| 3 | Fred
| Weinstein | f.weinstein@nanonull.com |
+----+-----------+-----------+--------------------------+
The SOURCE tab le
+----+-----------+-----------+--------------------------+
| id | firstname | lastname | email
|
+----+-----------+-----------+--------------------------+
| 1 | Mia
| Dahill
| NULL
|
| 2 | Fred
| Weinstein | f.weinstein@nanonull.com |
+----+-----------+-----------+--------------------------+
The TARGET tab le
Let's suppose your task is to merge data from the SOURCE table into the TARGET table. Only the
new records must be inserted into the TARGET table (in this example, "Tobie Hughey"). The
records which exist in both tables ("Mia Dahill" and "Fred Weinstein") must be ignored.
The task can be accomplished as follows.
1.
2.
3.
On the Insert menu, select Database. Follow the wizard steps to connect to the
database (see also Connecting to a Database). When prompted to add database objects,
select the table SOURCE.
On the Insert menu, select Database. Connect to the database again and add the table
TARGET to the mapping.
Draw the mapping connections between the source and target components.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
4.
Click the Action:Insert
Databases and MapForce
469
button and configure the database table actions as follows:
As illustrated above, a combination of "Ignore if.. Insert Rest" actions are defined. This
configuration means that, for each record, the mapping checks if:
firstname in the source is equal to firstname in the target, AND
lastname in the source is equal to lastname in the target, AND
email in the source is equal to email in the target.
If all the conditions above are true, the record is ignored (according to the requirement).
Otherwise, a new record is inserted into the target table. The id of the new record is generated by
the database, while the other fields (firstname, lastname, email) are populated with values
mapped from the source.
Importantly, the check box next to email enables or disables NULL-aware comparison for this
field. This check box must be selected, because email can contain NULL values (namely, "Mia
Dahill" has a NULL email address). To see the role played by this check box, try updating the
database two times: first time, with the check box selected, and a second time with the cleared
check box.
To update the database, click the Output tab and run the menu command Output | Run SQLScript.
If the check box is selected, MapForce has explicit indication that you want to treat the NULL
fields as equal. Therefore, the record "Mia Dahill" is not inserted in the target table, which is the
intended result.
If the check box is not selected, the record "Mia Dahill" is inserted in the target table (despite that
fact that it exists already), which is not the intended result. The reason is that no explicit
indication was given to MapForce that you want to treat NULL values as equal. A similar situation
would occur if you ran the following query against the database (this query retrieves no records
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
470
Data Sources and Targets
Databases and MapForce
because the NULL value is compared with the "=" operator so it is not NULL aware):
SELECT firstname, lastname, email FROM TARGET WHERE firstname = 'Mia' AND
lastname = 'Dahill' AND email = NULL;
In order to be NULL aware, the query above would have to be rewritten as follows:
SELECT firstname, lastname, email FROM TARGET WHERE firstname = 'Mia' AND
lastname = 'Dahill' AND email IS NULL;
Note:
7.2.3.12
The queries above are only for illustrative purposes and do not reflect the actual syntax of
internal queries generated by MapForce. When NULL awareness is enabled, MapForce
adapts the syntax of generated queries according to the database type (since various
database vendors have different approaches to handling null comparisons).
Database Table Actions Settings
Whenever you create a mapping connection to a database table, a Database Actions button
appears next to the affected table. Clicking this button opens Database Table Actions dialog box,
from where you can configure the database insert, update, and delete actions, as well as other
options.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
471
Datab ase Tab le Actions dialog b ox
Below is a description of the settings available on the Database Table Actions dialog box.
SQL statement to execute before first record
In this group box, you can define SQL statements that are executed before any actions defined
under Actions to execute for each record. Select the desired radio button:
None — No action is carried through. This is the default setting.
DELETE all records — All records from the selected table are deleted before any
specific table action defined in the Actions to execute for each record group box is
performed. Activate the also delete all records in all child tables check box if you
also want to get rid of the data stored in child tables of the selected table. For an
example, see Inserting Data into Multiple Linked Tables.
Custom SQL — Write a custom SQL statement to affect the complete table. Note that
support for multiple SQL statements in one query depends on the database, connection
method, and the driver used.
Actions to execute for each record
This group of settings specify the database actions that are to take place against this table when
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
472
Data Sources and Targets
Databases and MapForce
the mapping runs. To manage table actions, click the Append Action, Insert Action, or Delete
Action buttons. Multiple actions can be defined if necessary (for example, an "Update if..." action
followed by an "Insert Rest" action.
The defined table actions are processed from left to right. In the example above, the "Update if..."
action is processed first. If the update condition is not satisfied then the following action is
processed (in this example, the "Insert Rest" action). Note the following:
All the defined conditions of one action must be satisfied for the table action to be
executed. When this is the case, all those fields are updated where a connection exists
between the source and target items on the mapping. Any subsequent table actions (to
the right of an action whose condition matched) are ignored for that record.
If the defined condition is not satisfied, then the table action is skipped, and the next
action (to the right) is processed.
If none of the conditions are satisfied, no table action takes place.
Any table actions defined after "Insert All" or "Insert Rest" actions will never be executed,
because no column conditions exist for insert actions. A dialog box appears if this is the
case, stating that the subsequent table action columns will be deleted.
In the "NULL Equal" column, the check box next to each record, where applicable, enables you to
explicitly instruct MapForce that the column may contain NULL values and should be treated as
such (see also Handling Nulls in Database Table Actions).
When the mapping updates a table which has foreign key relationships to other tables, the
following options can be used:
Delete data in child tables
This option is meaningful when you select the "Update if..."
action for a parent table. It might be necessary if the number of
records in the source file is different from the number of records
in the target database, and you want to keep the database
synchronized (no orphaned data in child tables). See also
Options for Child Tables When Updating a Parent Table.
Ignore input child data
Use this option when you want to update a target parent table,
without affecting any of the child tables/records of that table.
See also Options for Child Tables When Updating a Parent
Table.
For examples which illustrate various combinations of actions, see:
Inserting Data into a Table
Inserting Data into Multiple Linked Tables
Updating a Table
Options for Child Tables When Updating a Parent Table
"Update if... Insert Rest" Action
"Delete if..." Action
"Ignore if..." Action
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
473
Use Transactions
Enables database transactions for this particular table action. For more information, see Using
Transaction Rollback.
Use Bulk Transfer
Enables bulk transfer (multiple INSERT statements as one query). Bulk transfer is supported if the
mapping is executed by MapForce Server and the database action is "Insert All". For more
information, see Bulk Inserts (MapForce Server).
7.2.4
Joining Database Data
In mappings that read data from databases, you can join database objects such as tables or
views by adding a Join component to the mapping. For example, you could combine data from
two or more tables bound by foreign key relationships, which is the typical way data is stored in
relational databases. The result would be the same as if you ran against the database an SQL
query where two or more tables are joined by means of an INNER JOIN operation.
Depending on the kind of data connected to the join component, the join operation can happen
either in standard (non-SQL) mode, or in SQL mode. Joins in non-SQL mode are undertaken by
MapForce, while joins in SQL mode are undertaken by the database from which the mapping
reads data.
Joins in non-SQL mode are more flexible because they support more component types as input
(for example, the join can be between tables from different databases, or between XML structures
and database tables). For an example of a non-SQL join, see Example: Join XML Structures. On
the other hand, a non-SQL join causes the mapping engine to perform memory-costly
comparisons (because the total number of comparisons represents the cross-join, or Cartesian
product, of all joined structures). Usually this process takes place very fast and is negligible in
mappings which are not data-intensive; however, if the joined data sources consist of a huge
number of records, then the mapping will require significant time to execute. If your mappings
must process a very large number of records, consider licensing MapForce Server Accelerator
Edition, which includes dedicated join optimization to speed up the mapping execution.
A join in SQL mode accepts only eligible database objects as input (such as tables or views), so
it is not as flexible as a non-SQL join. However, it offers better mapping performance because it is
executed natively by the database. For further information, see About Joins in SQL Mode.
Note:
Using a Join component is not the only way to join database tables or views. Joins
applicable to databases can also be performed by using SQL SELECT statements, see
SQL SELECT Statements as Virtual Tables. A major difference between SQL SELECT
statements and Join components is that the former are written by hand so they might
provide more flexibility. Join components are a simpler alternative if you do not feel
comfortable writing SQL statements by hand.
To add a Join component:
1.
Set the mapping transformation language to BUILT-IN (to do this, either click the
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
474
Data Sources and Targets
Databases and MapForce
toolbar button, or use the Output | Built-In Execution Engine menu command).
2.
On the Insert menu, click Join. Alternatively, click the Join (
) toolbar button. The
Join component appears on the mapping. By default, it accepts data from two structures,
so it has two nodes/rows inputs. If necessary, you can add new inputs to the join by
clicking the Add Input ( ) button, see Joining Three or More Structures.
3.
Connect the structures that are to be joined to the nodes/rows items of the join
component.
Add the condition for the join (or multiple conditions). To do this, right-click the Join
component and select Properties. Join conditions can also be added directly from the
mapping, by connecting the Boolean result of some function to the condition item of the
Join component. In certain cases when database tables are joined, the join condition (or
conditions) can be created automatically by MapForce. For further information, see
Adding Join Conditions.
4.
Notes:
Join components are supported when the target language of the mapping is set to BUILTIN. Code generation in C#, C++, or Java is not supported.
When a structure is not a valid or supported input source for the join, MapForce displays
hints either immediately directly on the mapping, or in the Messages window, when you
validate the mapping (see Validating Mappings).
Join components should not be connected to input parameters or results of inline userdefined functions. If such connections exist, validation errors will occur during mapping
validation.
When you connect eligible database components (such as tables or views) directly to a
Join component, an SQL mode (
) button automatically appears at the top-right
corner of the Join component. When enabled, this button provides special SQL features
applicable to the join operation (see About Joins in SQL Mode).
It is not possible to connect the output of the joined item to another Join component. If
necessary, however, you can connect a partial result of one join to another one.
7.2.4.1
About Joins in SQL Mode
When you connect eligible database components (such as tables or views) directly to a join
component, an SQL mode (
) button automatically appears at the top-right corner of the join
component. When SQL mode is enabled, the join operation is undertaken by the database from
where the mapping reads data. In other words, MapForce will internally send to the database a
query with the appropriate SQL syntax to select and combine data from all tables that take part in
the join. Importantly, you do not need to write any SQL; the required query is produced based on
how you visually designed the Join component on the mapping, as you will see in subsequent
examples.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Note:
Databases and MapForce
475
From a database and SQL perspective, MapForce-generated joins are always INNER
joins. That is, only records which satisfy the condition in both input sets are returned by
the Join component.
For SQL mode to be possible, the following conditions must be met:
1.
2.
3.
Both objects (tables or views) that are to be joined must be from the same database.
Both objects that are to be joined must originate from the same MapForce component.
(Note that you can quickly add/remove database objects in a component as follows: rightclick the database component, and select Add/Remove/Edit Database Objects from
the context menu.)
The Join condition (or conditions) must defined only from the component properties (by
right-clicking the header of the join component, and selecting Properties), and not on the
mapping (see also Adding Join Conditions).
Note:
When database tables are joined in SQL mode, MapForce will create the join condition
(or conditions) automatically, based on foreign key relationships detected between tables.
For automatic join conditions to happen, the database tables must be in a child-parent
relationship on the MapForce component (that is, one table must be "parent" or "child" of
another one on the component), see Example: Join Tables in SQL Mode.
4.
All database tables must not yet be in the current target context. For example, if the
mapping is designed in such a way that tables are queried by the mapping before the join
operation, this could make the join impossible. For more information about how a
mapping is executed, see Mapping Rules and Strategies.
You can view or control the SQL mode through the SQL (
the join component, as follows:
) button at the top-right corner of
SQL mode is disabled (join will be executed by MapForce (or, if applicable, by
MapForce Server).
SQL mode is enabled (join will be executed by the database).
If the
button is missing, this means that SQL mode is not meaningful or not supported for the
data that is being joined.
In certain cases, the SQL mode must be explicitly disabled (
), for example:
When your mapping requires join conditions outside of the join component properties
(that is, conditions defined on the mapping and connected to the condition item of the
join component).
When you want to join tables from different databases. Use a standard (non-SQL) join if
you need to join tables from different databases.
It is often the case that joined database tables or views contain identical field names in both
joined structures. When SQL mode is enabled, such items appear on the component prefixed by
the keyword "AS". For example, if two joined tables contain an "id" field, this field appears as "id"
on the first joined table and as "id AS id2" on the second joined table. Joined tables can also
produce alias names, for example, if the same table is joined to itself.
The alias field or table names are important if you need to refer to them subsequently on a
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
476
Data Sources and Targets
Databases and MapForce
mapping. For example, imagine a case when you want to filter or sort the result of the join. To
achieve this, the output of the join component can be connected to a SQL WHERE/ORDER
component, where you would enter the SQL WHERE and ORDER BY clauses.
To refer to a field from the WHERE clause, write the table name, followed by a dot (.) character,
followed by the field name. To refer to a table alias, use the alias name as it appears on the Join
component. In the ORDER BY clause, you can either use the same technique (table.field), or
write just the alias field name (the name that appears after "AS").
For an example mapping which uses SQL WHERE/ORDER clauses, see Example: Join Tables in
SQL Mode.
Note:
7.2.4.2
SQL WHERE/ORDER components are not allowed between a database table and the
join component; they can be added only after (but not before) a join component. For more
information about SQL WHERE/ORDER components, see Filtering and Sorting Database
Data (SQL WHERE/ORDER).
Example: Join Tables in SQL Mode
This example illustrates how to join data from two database tables, using a MapForce join
component. The join operation is performed in SQL mode, as described in About Joins in SQL
Mode. Note that joining three or more tables works in a very similar way, see also Example:
Create CSV Report from Multiple Tables.
The example is accompanied by a mapping sample which is available at the following path:
<Documents>\Altova\MapForce2017\MapForceExamples\Tutorial
\JoinDatabaseTables.mfd.
JoinDatab aseTab les.mfd
The purpose of the mapping above is to combine data from two source database tables into a
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
477
single target CSV file. As illustrated in the database diagram below, the first table (users) stores
people's addresses and the second table (addresses) stores people names and email addresses.
The two tables are linked by a common field (id in users corresponds to user_id in addresses).
In database terminology, this kind of relation is also known as a "foreign key relationship".
For convenience, the image below illustrates the actual data in both tables.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
478
Data Sources and Targets
Databases and MapForce
Each user record in the users table can have zero or more addresses in the addresses table. For
example, a user may have one address of type "home", or two addresses (one of type "home"
and another of type "work"), or no address at all.
The goal of the mapping is to retrieve full data (name, surname, email, city, street, number) of all
users that have at least one address in the addresses table. It should also be possible to easily
retrieve only addresses of a specific kind (for example, only home addresses, or only work
addresses). The kind of addresses to retrieve ("home" or "work") should be supplied as a
parameter to the mapping. The retrieved people records must be sorted alphabetically by last
name.
The mapping requirement will be accomplished with the help of a Join component, as illustrated in
the steps below.
Note:
Using a Join component is not the only way to join database tables or views. Joins
applicable to databases can also be performed by using SQL SELECT statements, see
SQL SELECT Statements as Virtual Tables. A major difference between SQL SELECT
statements and Join components is that the former are written by hand so they might
provide more flexibility. Join components are a simpler alternative if you do not feel
comfortable writing SQL statements by hand.
Step 1: Add the source database
1.
On the Insert menu, click Database. (Alternatively, click the Insert Database
Altova MapForce 2017 Professional Edition
toolbar
© 2017 Altova Gmb H
Data Sources and Targets
2.
3.
4.
Databases and MapForce
479
button).
Select "SQLite" as database kind, and click Next.
Browse for the Nanonull.sqlite file available in the folder: <Documents>\Altova
\MapForce2017\MapForceExamples\Tutorial\, and click Connect.
When prompted, select the addresses and users tables.
Step 2: Add the join component
1.
2.
3.
On the Insert menu, click Join. (Alternatively, click the Join
toolbar button).
Draw a connection from the users table to the first input of the join component.
Expand the users table and draw a connection from the addresses table (child of users)
to the second input of join component. The button enables you to add more tables if
necessary; however, in this example, only two tables are being joined.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
480
Data Sources and Targets
Note:
4.
Databases and MapForce
It is also possible to add the connection directly from the addresses table (the one which
is not child of users); however, in this case, the join conditions would have to be defined
manually, as described in Adding Join Conditions. For the purpose of this example, make
sure to create the connections as shown above. This ensures the required join condition
is created automatically.
Click the Define Join Condition
button available on the join component. Notice that
the join condition has been created automatically (users.id = addresses.user_id).
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
481
Step 3: Add the target CSV component
1.
2.
3.
On the Insert menu, click Text File. (Alternatively, click the Insert Text File
toolbar
button).
When prompted to choose a text processing mode, select Use simple processing for
standard CSV... .
Click Append Field several times to create seven CSV fields. Leave all other settings as
is.
4.
Double-click the title cell of each field to give it a descriptive name (this will make your
mapping easier to read).
5.
Draw the mapping connections between the Join component and the CSV component as
shown below. The connection between the joined item of the join component and the
Rows item of the target component means "create as many records (rows) in the target as
there are records that meet the join condition".
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
482
Data Sources and Targets
Databases and MapForce
Step 4: Add the SQL WHERE/ORDER condition and input parameter
1.
2.
Right-click the connection between the joined item of the Join component and the Rows
item of the target CSV component, and select Insert SQL-WHERE/ORDER.
Enter the WHERE and ORDER BY clauses as shown below.
3.
On the mapping, add an input component (using the Insert | Insert Input menu
command) and connect its output to the address_type parameter created in the previous
step.
4.
Double-click the input component and configure it as shown below. A design-time value is
required (in this case, "home") to preview the mapping output in MapForce. If you want
the preview to retrieve work addresses, replace this value with "work".
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
483
The mapping explained
The join condition automatically created in step 2 ensures that only records which satisfy the join
condition users.id = addresses.user_id are copied to the target. The join condition was added
automatically because the two tables are bound by a foreign key relationship and the mapping
connections were drawn accordingly (for more information about table relationships, see Handling
Database Relationships). Although not applicable to this example, it is also possible to define join
conditions manually, see Example: Create CSV Report from Multiple Tables.
The two source tables are from the same database and from the same component, so this join
benefits from the SQL (
) mode. Since SQL mode is enabled, the join operation is undertaken
by the database, not by MapForce. In other words, an INNER JOIN statement is generated
internally by MapForce and sent to the database for execution.
The SQL WHERE/ORDER component added in step 4 enables filtering (to retrieve either home or
work addresses) and sorting the recordset. Notice that the WHERE clause created a parameter
:address_type of type string. This parameter makes it possible to supply the address kind
(home or work) from the mapping. For more information about SQL WHERE/ORDER, see Filtering
and Sorting Database Data (SQL WHERE/ORDER).
Finally, the input component makes it possible to supply the actual parameter value when the
mapping runs. Note that, when the mapping runs outside MapForce (for example, when it is
executed by MapForce Server on a different machine), the input must be supplied at mapping
runtime as a command-line parameter, so the design-time value mentioned above is ignored. For
more information, see Supplying Parameters to the Mapping.
7.2.4.3
Example: Create CSV Report from Multiple Tables
This example illustrates how to join multiple database tables for the purpose of extracting data
into a single report in CSV format. The database used in this example is called Nanonull.sqlite
and is available at the following path: <Documents>\Altova\MapForce2017
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
484
Data Sources and Targets
Databases and MapForce
\MapForceExamples\Tutorial\. This database stores information about a fictitious business
(which includes orders, products, users and their addresses). As is typically the case with
relational databases, the information is normalized and spread across multiple tables. For
example, the users table stores user personal data (which includes first name, last name, and
email). The database also stores information about products ordered by users, in two different
tables: orders (which includes the unique ID of the order, and the time when it took place) and
orderedproducts (which includes a list of products ordered, and their quantity). Furthermore, the
names of the products themselves is stored in a separate table called products.
The goal of the example is to produce a report based on data extracted from various tables, so as
to make it clear who ordered certain products, when, and in which quantity. To achieve the
mapping goal, follow the steps below:
1.
2.
3.
4.
On the Insert menu, click Database.
When prompted to select a database kind, click SQLite, and then click Next.
Browse for the Nanonull.sqlite database mentioned above, and click Connect.
When prompted, select the tables orderedproducts, orders, products, and users, and
click OK.
5.
Add a Join component to the mapping and create four nodes/rows items by clicking the
Add input ( ) button.
Connect the four tables from the database component to the corresponding input items of
the Join component.
6.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Note:
Databases and MapForce
485
In an alternative scenario, you could connect to the Join component the table
orderedproducts, then the table orders (the one which is nested under it, not the one
at the same level), and so on, so that all joined tables are nested under the same "root"
table, see also Handling Database Relationships. The mapping result would be the same
if you joined tables this way. The difference is that in this example the join conditions
must be created manually, as shown below, whereas in the alternative scenario the join
conditions would be created automatically by MapForce. For an example of joining tables
without having to define join conditions manually, see Example: Join Tables in SQL
Mode. Another mapping where all joined tables are under the same "root" table is
available at the following path: <Documents>\Altova\MapForce2017
\MapForceExamples\DB_Denormalize.mfd.
In this example, the tables connected to the Join component have the following order:
1.
2.
3.
4.
orderedproducts
orders
products
users
This order affects how the respective structures are displayed on the "Define Join Condition"
dialog box, when you click the Define Join Condition (
) button. Namely, the first table
(orderedproducts) appears by default under Structure 1, and the table immediately after it
(orders) appears under Structure 2.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
486
Data Sources and Targets
Databases and MapForce
To define the first join condition, click the order_id item in the left pane and the id item in the
right pane. Now the fields orderedproducts.order_id and orders.id. are paired:
So far, only two tables have been joined. To define join conditions which involve a third table,
select the desired table from the drop-down list available above the right pane. The left pane
displays in this case all tables that occur before it on the Join component. For example, if you
select products on the right side, then the left side displays orderedproducts and orders
(since these tables occur before products on the Join component). You can now pair fields of
table products with fields of tables preceding it (in this case, orderedproducts.product_id and
products.id).
To join a fourth table (users), select the users table from the drop-down list. You can now pair the
fields orders.user_id and users.id.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
487
Now that all required join conditions have been defined, items of the Join component can be
further mapped to a target component. To finish the mapping, add a CSV component (see CSV
and Text Files), and connect items from the Join component to the target CSV component as
illustrated below:
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
488
Data Sources and Targets
Databases and MapForce
The mapping illustrated above produces a report (in CSV format) compiled from all four tables
involved in the join, as follows:
ID of the order (taken from the orderedproducts table)
Quantity of ordered items (taken from the orderedproducts table)
Time when the order took place (taken from the orders table)
Name of the product ordered (taken from the products table)
First name and last name of the user who ordered the product (taken from the users
table).
7.2.5
Filtering and Sorting Database Data (SQL WHERE/ORDER)
When you need to filter and sort database data, use an SQL WHERE/ORDER component. This
enables you to manually enter, from the MapForce graphical user interface, a SQL WHERE
clause that filters data. Optionally, you can also specify an ORDER BY clause if you want to sort
the recordset by a particular database field, in ascending or descending order.
The SQL WHERE/ORDER component must be connected to a table or field of a database
mapping component. It is also possible to connect the SQL WHERE/ORDER to a Join
component, if you need to filter the joined set or records (see Joining Database Data).
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
489
Adding a SQL WHERE/ORDER component to the mapping
1.
On the Insert menu, click SQL WHERE/ORDER. By default, the SQL WHERE/ORDER
component has the following structure:
2.
Connect a source database table or field to the table/field item of the SQL WHERE/
ORDER. For an example, open the mapping DB_PhoneList.mfd from the folder
<Documents>\Altova\MapForce2017\MapForceExamples\. In this mapping, the SQL
WHERE/ORDER is used to filter from the source table "Person" all records where the
last name begins with letter "B".
3.
Double-click the header of the SQL WHERE/ORDER component (or right-click it and
select Properties from the context menu). This opens the "SQL WHERE/ORDER
Properties" dialog box.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
490
Data Sources and Targets
4.
Databases and MapForce
Type the SQL WHERE clause in the text box at the top. Optionally, type the ORDER BY
clause. The image above illustrates the WHERE and ORDER BY clauses defined in the
DB_PhoneList.mfd mapping (these settings are further explained below). For more
examples, see Creating WHERE and ORDER BY Clauses.
Supplying parameters to a SQL WHERE/ORDER
The SQL WHERE/ORDER component used in the mapping DB_PhoneList.mfd defines a
WHERE clause as follows:
Last LIKE :Name
"Last" refers to the name of a database field in the connected table. "LIKE" is an SQL operator.
":Name" creates a parameter called "Name" on the mapping.
Parameters in SQL WHERE/ORDER components are optional; they are useful if you want to
pass a value to the WHERE clause from the mapping. Without parameters, the WHERE clause
above could have been written as follows:
Last LIKE "B%"
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
491
This would retrieve all persons whose last name begins with letter "B". In order to make this query
even more flexible, we added a parameter instead of "B%". This makes it possible to supply any
other letter from the mapping (for example, "C", and thus retrieve people whose last name begins
with "C" simply by changing a constant, or a mapping input parameter).
Appearance of SQL WHERE/ORDER components
An important thing about SQL WHERE/ORDER components is that they change appearance
depending on the settings defined in them. This way you can quickly view directly from the
mapping what the SQL WHERE/ORDER component does, for example:
A WHERE clause has been defined.
A WHERE clause with a parameter has been defined. The parameter
"Name" is visible under the "table/field" item.
A WHERE clause with a parameter has been defined. Additionally, an
ORDER BY clause has been defined. The sorting is indicated by the A-Z
sort icon.
Placing the mouse cursor over the SQL WHERE/ORDER header opens a tooltip displaying the
various clauses that have been defined.
7.2.5.1
Creating WHERE and ORDER BY Clauses
After an SQL WHERE/ORDER component is added to the mapping, it needs a WHERE condition
(clause) through which you specify how exactly you want to filter the data connected to the
component. The WHERE condition must be entered in the "SQL WHERE/ORDER Properties"
dialog box of MapForce, as shown in the previous section.
Writing a WHERE condition from MapForce is similar to writing the same SQL clause outside
MapForce. Use the syntax applicable to the SQL dialect of the corresponding database. For
example, you can use operators, wildcards, as well as sub-selects or aggregate functions. To
create parameters that you can pass from the mapping, enter a semi-colon character ( : ) followed
by the parameter name.
Note:
When you finish writing the WHERE clause and click OK, MapForce validates the
integrity of the final SQL statement. A dialog box prompts you if there are syntax errors.
The table below lists some typical operators that can be used in the WHERE clause:
Operator
Description
=
Equal
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
492
Data Sources and Targets
Databases and MapForce
Operator
Description
<>
Not equal
<
Less than
>
Greater than
>=
Greater than/equal
<=
Less than/equal
IN
Retrieves a known value of a column
LIKE
Searches for a specific pattern
BETWEEN
Searches between a range
Use the % (percentage) wildcard to represent any number of characters in a pattern. For example,
to retrieve all records ending in "r" from a field called lastname, use the following expression:
lastname = "%r"
When querying databases that support storing and querying of XML database data (for example,
IBM DB2, Oracle, SQL Server), you can use XML functions and keywords applicable to that
particular database, for example:
xmlexists('$c/Client/Address[zip>"55116"]' passing
USER.CLIENTS.CONTACTINFO AS "c")
See also Example: Extracting Data from IBM DB2 XML Type Columns.
Optionally, if you want to sort the retrieved recordset by a particular field, add an ORDER BY clause
in the corresponding text box of the "SQL WHERE/ORDER Properties" dialog box. To sort by
multiple fields, separate the field names by commas. To change the sort order, use the ASC and
DESC keywords. For example, the following ORDER BY clause retrieves records ordered by
lastname, and then by firstname, in descending order:
lastname, firstname DESC
Example 1
The following WHERE condition is attached to the Person table of the altova.mdb database
component. It retrieves those records where First and Last are greater than the letter "C". In
other words, it retrieves all names from "Callaby" onwards.
First > "C" AND Last > "C"
Note how the connections are placed:
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
493
The connection to table/field originates in the table that you want to query, "Person" in
this case.
The result output is connected to a "parent" item of the fields that are queried/filtered, in
this case the Person item.
Example 2
The following WHERE condition creates a parameter Name which then appears in the SQL
WHERE/ORDER component on the mapping.
Last LIKE :Name
The constant component %S supplies the value of the Name parameter. The wildcard % denotes
any number of characters. This causes the mapping to search for a pattern in the column
"Last" (all last names ending in "S").
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
494
Data Sources and Targets
Databases and MapForce
Example 3
The following WHERE condition creates two parameters, PhoneUpper and PhoneLower, to which
the current values of PhoneExt are compared. The upper and lower values are supplied by two
constant components shown in the diagram below.
PhoneExt < :PhoneUpper and PhoneExt > :PhoneLower
The WHERE condition in this example could also be written using the BETWEEN operator:
PhoneExt BETWEEN :PhoneUpper and :PhoneLower
7.2.6
SQL SELECT Statements as Virtual Tables
MapForce supports the creation of SQL SELECT statements with parameters in database
components. These are table-like structures that contain the fields of the result set generated by
the SELECT statement. These structures can then be used as a mapping data source, like any
table or view defined in the database.
When using Inner/Outer joins in the SELECT statement, fields of all tables are included
in the component.
Expressions with correlation names (using the SQL "AS" keyword) also appear as a
mappable items in the component.
Database views can also be used in the FROM clause.
SELECT statements can contain parameters which use the same syntax as the SQL
WHERE/ORDER component.
Once the SELECT statement has been added to a database component, the fields returned by it
are available for mapping, for example:
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
495
The number of visible lines of the SELECT statement is configurable. To define the number of lines
you want to see on the component, select the menu command Tools | Options, click the
General tab and enter the number of lines in the Mapping View group.
7.2.6.1
Creating SELECT Statements
You can create SELECT statements on any mapping which contains a database component. If
your mapping does not contain a database yet, add a database first (see Connecting to a
Database ). For the scope of this example, select the menu command Insert | Insert Database
and follow the wizard steps to connect to the altova-products.mdb file available in the
<Documents>\Altova\MapForce2017\MapForceExamples\Tutorial\ folder.
To create a SELECT statement:
1.
Right-click the title of the database component, and select Add/Remove/Edit Database
Objects. (As an alternative, select the database component, and then select the menu
command Component | Add/Remove/Edit Database Objects).
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
496
Data Sources and Targets
2.
3.
Databases and MapForce
Do one of the following:
o To generate the SELECT statement from an existing table, right-click any table and
select Generate and add an SQL statement from the context menu. You will be
able to edit the generated statement afterwards.
o To write a custom SELECT statement, click the Add/Edit SELECT Statement
button.
Edit or create the statement as required. For example, the SELECT statement below is
valid for the altova-products.mdb file available in the <Documents>\Altova
\MapForce2017\MapForceExamples\Tutorial\ folder. The Price field is the product of
the two fields, Quantity and UnitPrice, and is declared as a correlation name ( AS
Price ).
SELECT *, (Quantity*UnitPrice) AS Price
From Orders
INNER JOIN Products
ON Orders.ProductID = Products.ProductID
Where Orders.Quantity > 2
4.
Click Add SELECT Statement. Notice that the SELECT statement is now visible as a
database object, similar to how tables, views, and procedures are visible.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
5.
Databases and MapForce
497
Click OK. The SELECT statement is also displayed on the database component, and you
can map data from any of the fields returned by the SELECT query.
Important notes:
All calculated expressions in the SELECT statement must have a unique correlation
name (like "AS Price" in this example) to be available as a mappable item.
If you connect to an Oracle or IBM DB2 database using JDBC, the SELECT statement
must have no final semicolon.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
498
Data Sources and Targets
Databases and MapForce
To remove a previously added SELECT statement:
1.
2.
7.2.6.2
Right-click the title of the database component, and select Add/Remove/Edit Database
Objects.
Right-click the SELECT statement you want to delete, and select Remove Select
Statement.
Example: SELECT with Parameters
This example shows you how to create a MapForce mapping which reads data from a Microsoft
Access database and writes it to a CSV file. In particular, the mapping described in this example
uses a custom database SELECT query with a parameter. The SELECT statement combines
data from multiple tables. Then, the results are supplied to the mapping for further processing.
The example is accompanied by a mapping design (.mfd) file available at the following path:
<Documents>\Altova\MapForce2017\MapForceExamples\Tutorial\select-component.mfd.
You might want to open this sample file and analyze it first, or follow the steps below to create it
from scratch.
Although this example uses a Microsoft Access database, the process works in the same way for
other database types. For information about connecting to other databases, see Connecting to a
Database.
The goals are as follows:
1.
2.
3.
We must select from the database only those orders where the number of ordered items
exceeds a custom value. This custom value should be supplied as a parameter to the
mapping. To achieve this goal, we will create a custom database SELECT statement that
takes an input parameter.
In the Access database, the date format is YYYY-MM-DD HH-MI-SS. In the CSV file, the
time part must be stripped, so the format should be YYYY-MM-DD. To achieve this goal, we
use the date-from-datetime function available in MapForce.
The resulting CSV file must have the name OrdersReport.csv.
Step 1: Add the SELECT structure
1.
2.
On the Insert menu, click Database.
Select Microsoft Access (ADO), and follow the wizard steps to connect to the altovaproducts.mdb file available in the <Documents>\Altova\MapForce2017
\MapForceExamples\Tutorial\ folder.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
3.
Databases and MapForce
499
On the Insert Database Objects dialog box, click Add/Edit SELECT Statement, and
enter the following query:
SELECT *, (Quantity * UnitPrice) AS Price
FROM Orders
INNER JOIN Products
ON Orders.ProductID = Products.ProductID
WHERE Orders.Quantity > :Quantity
This query uses a join between the Orders and Products tables, and retrieves all fields
(*), and a computed value (AS Price). The query also specifies the :Quantity parameter
in the WHERE clause.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
500
Data Sources and Targets
Databases and MapForce
4.
Click Add SELECT statement.
5.
6.
Click OK. The altova-products component has now been added to the mapping area.
On the altova-products component, click
and select Insert Call with Parameters.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
501
A new structure (SELECT_Statement) is now available on the mapping. It is split into two
parts: the left part supplies input connectors and the right part supplies output
connectors. Notice that the left part also includes the Quantity parameter defined
previously.
Step 2: Add the input parameter
1.
2.
3.
On the Insert menu, click Insert Input.
Type "Quantity" as name.
Under Design-time Execution, enter a parameter value to be used for executing the
mapping during the design phase (in this example, "2"). For more information, see
Supplying Parameters to the Mapping.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
502
Data Sources and Targets
Databases and MapForce
You can now connect the input parameter to the database call structure, as shown below.
Step 3: Add the target CSV component
1.
2.
3.
On the Insert menu, click Text File.
Select Use simple processing for standard CSV..., and then click Continue.
On the Component Settings dialog box, click Append Field and add nine new fields. It is
recommended that you give to the CSV fields the same name as the name of the
database fields, as shown below. This will help you save time later when drawing mapping
connections. For more information about these settings, see Setting the CSV Options.
4.
Create a connection between the result node of the SELECT structure and the Rows
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
503
node of the CSV component.
Because most of the fields in the CSV component have the same name as their database
equivalent, mapping connections will likely be drawn automatically when you connect
result to Rows. If this does happen, select the Connection menu and make sure that
the Auto Connect Matching Children option is enabled. The only mapping item that
you have to connect manually is ProductID, since there is no field with this name in the
SELECT structure.
Step 4: Convert the date
In the Libraries window, search for the date-from-datetime function and drag it to the mapping
area. Then connect its input and output as shown below.
Step 5: Set the name of the output file
To set the name of the output file to OrdersReport.csv, double-click the CSV component, and
enter the value in the Output File box.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
504
7.2.7
Data Sources and Targets
Databases and MapForce
Mapping XML Data to / from Database Fields
MapForce enables you to map data to or from database fields (columns) that store XML content.
This means that XML data stored by the database field (column) can be extracted and written to
any other structure supported by MapForce, and the other way round. You can map data as
follows:
1.
2.
To or from fields of a dedicated XML type (for example, Xml in SQL Server, XMLType in
Oracle). Reading or writing XML to/from dedicated XML fields is applicable to databases
that have native support for XML (such as IBM DB2, Oracle, and SQL Server).
To or from text fields storing XML content (for example, Text, Varchar). This applies to
any database where the text field has sufficient length to store an XML document.
In either of the cases, a valid XML schema must exist for each database column to/from which
you want to map data. When a database column stores XML, MapForce provides you with the
choice to assign an XML schema directly from the database (if supported by the database), or
select a schema from an external file. You can assign one XML schema per database column. If
the schema has multiple root elements, you can select a single root element of that schema.
When XML is stored as a string field in a database, the character encoding of the XML document
is that of the underlying string field. If the database field does not store text as Unicode, some
characters cannot be represented.
Some databases support XML encoding for XML fields (which may not necessarily be the same
as that of the database character set). If supported by the database, the XML document encoding
declaration is assumed to be the one declared in the XML field. For information about the XML
encoding support provided by various databases, refer to their documentation.
7.2.7.1
Assigning an XML Schema to a Database Field
This topic illustrates how to assign a schema to a field that is natively defined as XML type in the
database. The instructions below use SQL Server 2014 and the Adventure Works 2014 database.
The latter can be downloaded from the CodePlex website ( https://
msftdbprodsamples.codeplex.com/ ). Note that mapping of data to or from XML fields works in the
same way with other database types that support XML fields.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
505
To add the Adventure Works 2014 database as a mapping component:
1.
2.
3.
On the Insert menu, click Database, and follow the wizard to connect to the database
using your preferred method (ADO or ODBC). For more information, see Connecting to
Microsoft SQL Server (ADO) and Connecting to Microsoft SQL Server (ODBC). NOTE: If
you use the SQL Server Native Client driver, you might need to set the Integrated
Security property to a space character (see Setting up the SQL Server Data Link
Properties ).
On the Insert Database Object dialog box, expand the Production schema, and then
select the ProductModel table.
Click OK.
The database table has now been added to the mapping area. Notice that this table has two fields
of XML type: CatalogDescription and Instructions:
For the structure of the XML fields to appear on the mapping, the XML schema of the field content
is required. Right-click the Instructions field and select Assign XML Schema to Field from the
context menu.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
506
Data Sources and Targets
Databases and MapForce
In this particular example, you will assign a schema to the Instructions field directly from the
database. To do this, select the Production.ManuInstructionsSchemaCollection item next to
the Database option, and then click OK.
The structure of the XML field now appears on the component. You can now draw connections
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
507
(and map data) to or from this field.
7.2.7.2
Example: Writing XML Data to a SQLite Field
This example walks you through the steps required to create a MapForce mapping which reads
data from multiple XML files and writes it to a SQLite database. The goal of the mapping is to
create, for each source XML file, a new database record in the SQLite database. Each record will
store the XML document as a TEXT field.
All the files used in this example are available at the following path: <Documents>\Altova
\MapForce2017\MapForceExamples\Tutorial\. The file names are as follows:
The mapping design file
XmlToSqliteField.mfd
The source XML files
bookentry1.xml
bookentry2.xml
bookentry3.xml
The XML schema used for
validation
books.xsd
The target SQLite
database
Library.sqlite
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
508
Data Sources and Targets
Databases and MapForce
To achieve the goal of the mapping, the following steps will be taken:
1.
2.
3.
Add the XML component and configure it to read from multiple files.
Add the SQLite database component and assign an XML schema to the target TEXT field.
Create the mapping connections and configure the database INSERT action.
Step 1: Add the XML component
1.
2.
On the Insert menu, click XML Schema/File and browse for the books.xsd schema
located in the <Documents>\Altova\MapForce2017\MapForceExamples\Tutorial\
directory. When prompted to supply a sample XML file, click Skip. When prompted to
select a root element, select Books.
Double-click the component header and type bookentry*.xml in the Input XML File
box. This instructs MapForce to read all XML files whose name begins with "bookentry-"
in the source directory. For more information about this technique, see Processing
Multiple Input or Output Files Dynamically.
Step 2: Add the SQLite component
On the Insert menu, click Database, and follow the wizard to connect to the Library.sqlite
database file from the <Documents>\Altova\MapForce2017\MapForceExamples\Tutorial\
directory (see also Connecting to an Existing SQLite Database ). When prompted to select the
database objects, select the BOOKS table.
The database field where XML content will be written is called metadata. To assign an XML
schema to this field, right-click it and select Assign XML Schema to Field from the context
menu.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
509
In this tutorial, the schema assigned to the metadata field is the same one used to validate the
source XML files. Click Browse and select the books.xsd schema from the <Documents>
\Altova\MapForce2017\MapForceExamples\Tutorial\ directory:
The books.xsd schema has two elements with global declaration: book and books. In this
example, we will set book as the root element of the XML written to the database field. Click
Choose, and select book as root element:
Step 3: Create the mapping connections and configure the database INSERT
action
Create the mapping connections as follows:
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
510
Data Sources and Targets
Databases and MapForce
As shown above, the connection from book to book is a "Copy-All" connection, since both the
source and target use the same schema and the names of child elements are the same. For
more information about such connections, see Copy-all connections.
The topmost connection (books to BOOKS) iterates through each book element in the source and
writes a new record in the BOOKS table. Click the A:In button on the database component and
set the database update settings as shown below:
The DELETE all records option instructs MapForce to delete the contents of the BOOKS table
before inserting any records.
The Insert All actions specify that a database INSERT query will take place. The field id is
generated from the database itself, while the field metadata will be populated with the value
provided by the mapping.
Make sure to save the mapping before running it.
To run the mapping and view the generated output, click the Output tab. Note that this action
does not update the database immediately. When you are ready to run the generated database
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
script, select the menu command Output | Run SQL Script (or click the
7.2.7.3
511
toolbar button).
Example: Extracting Data from IBM DB2 XML Type Columns
This example illustrates how to extract data from IBM DB2 database columns of XML type and
write it to a target CSV file. It also illustrates how to use XQuery statements embedded into SQL
in order to retrieve XML content conditionally. The example requires access to an IBM DB2
database where you have permission to create and populate tables.
First, let's prepare the database so that it actually contains XML data. This can be done either in
a database administration tool specific to your database, or directly in MapForce. To do this
directly in MapForce, follow the steps below:
1.
2.
3.
Create a new mapping and click the DBQuery tab.
Click Quick Connect (
) and follow the wizard steps to create a new database
connection (see also Database Connection Examples).
Paste the following text into the SQL Editor. This SQL query creates a database table
called ARTICLES and populates it with data.
-- Create the table
CREATE TABLE
ARTICLES (
id INTEGER NOT NULL,
article XML ) ;
-- Populate the table
INSERT INTO ARTICLES VALUES
(1, '<Article>
<Number>1</Number>
<Name>T-Shirt</Name>
<SinglePrice>25</SinglePrice>
</Article>'),
(2, '<Article>
<Number>2</Number>
<Name>Socks</Name>
<SinglePrice>230</SinglePrice>
</Article>'),
(3, '<Article>
<Number>3</Number>
<Name>Pants</Name>
<SinglePrice>34</SinglePrice>
</Article>'),
(4, '<Article>
<Number>4</Number>
<Name>Jacket</Name>
<SinglePrice>5750</SinglePrice>
</Article>');
4.
Click the Execute (
) button. The query execution result is displayed in the Query
Results window. If the query is executed successfully, four rows are added to the newly
created table.
Next, we will create a mapping which retrieves XML data from the ARTICLES table created above
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
512
Data Sources and Targets
Databases and MapForce
conditionally. The goal is to retrieve from the ARTICLES column only articles with a price greater
than 100.
Step 1: Add the database
1.
2.
3.
Click the Mapping tab to switch back to the mapping pane.
On the Insert menu, click Database, and follow the wizard steps to connect to the
database.
When prompted to select the database objects, select the ARTICLES table created
previously.
Step 2: Assign the schema to the XML type field
1.
Right-click the ARTICLE item of the component, and select Assign XML Schema to
field from the context menu.
2.
Select File, and browse for the following schema: <Documents>\Altova\MapForce2017
\MapForceExamples\Tutorial\DB2xsd.xsd.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
513
Step 3: Add the SQL WHERE/ORDER component
1.
2.
On the Insert menu, click SQL WHERE/ORDER.
Connect the ARTICLE XML type column to the input of the SQL WHERE/ORDER.
3.
In the SQL-WHERE/ORDER Properties dialog box, enter the following text:
XMLEXISTS('$a/Article[SinglePrice>100]' PASSING ARTICLE as "a")
The text above represents the "WHERE" part of the SQL query. At mapping runtime, it
will be combined with the "SELECT" part displayed on the dialog box. This statement
uses the XMLEXISTS function and syntax specific to IBM DB2 databases.
Step 4: Add the target CSV file
1.
2.
3.
4.
On the Insert menu, click Text File.
When prompted, select Use simple processing for standard CSV... , and click
Continue.
Click Append Field three times to add three fields which will store the article number,
name, and price, respectively. Leave all other settings as is.
Draw the mapping connections as shown below.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
514
Data Sources and Targets
Databases and MapForce
You can now preview the mapping result, by clicking the Output tab. As expected, only articles
with price greater than 100 are shown in the output.
7.2.8
Browsing and Querying Databases
MapForce has a dedicated Database Query pane (also called DB Query) that allows you to query
a database independently of the mapping process. Such direct queries are not saved together
with the mapping *.mfd file but provide a convenient way to browse or modify the contents of a
database directly from MapForce.
A separate DB Query pane exists for each currently active mapping. You can create multiple
active connections, to different databases, within each DB Query pane. Note that the connections
created from the DB Query pane are not part of the mapping and thus are not preserved after you
close MapForce, unless you define them as Global Resources (see Global Resources Databases ).
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
515
The Database Query pane consists of the following parts:
Database Browser, which displays connection info and database tables
SQL Editor, in which you write your SQL queries
Results tab, which displays the query results in tabular form
Messages tab, which displays warnings or error messages.
The upper area of the Database Query pane contains the connection controls allowing you to
define the working databases, as well as the connection and database schemas.
7.2.8.1
Selecting or Connecting to a Database
For each database that you want to query, a database connection must be created. If your
mapping already includes a database component, you can select the existing database
connection from the upper area of the DB Query pane (by default, the connection is "Offline") and
start exploring the database objects and run queries.
If your mapping does not include any database component, or if you want to connect to a new
database, click Quick Connect (
) and follow the wizard steps to create a new database
connection (see Examples ). You can also select an existing database connection from Global
Resources, if one has been defined as such (see Global Resources - Databases ).
Once you are connected to the database, you can create database queries using one of the
following methods:
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
516
Data Sources and Targets
Databases and MapForce
Import the SQL query into the SQL Editor pane from an existing SQL file.
Write the query in the SQL Editor pane.
Right-click an object in the Database Browser pane and generate a query (typically,
SELECT).
When you are ready to run the query displayed in the SQL Editor pane, click the Execute
button. The database data is retrieved and displayed in the Results tab in tabular form. Note that
the status bar displays the "Finished Retrieval" message (
), and other
pertinent information about the query results.
Once the "Finished Retrieval" message is displayed, you can search, sort, or copy to clipboard
the search results (see Database Query - Results & Messages tab ).
7.2.8.2
Creating and Editing SQL Statements
The SQL Editor is used to write and execute SQL statements. It displays any SQL statements
that you may have generated automatically, loaded from existing SQL scripts, or written
manually. The SQL Editor supports autocompletion (see Auto-Completion), regions, and line or
block comments.
The SQL Editor toolbar provides the following buttons:
Toggle Browser: Toggles the Browser pane on and off.
Toggle Result: Toggles the Result pane on and off.
Execute (F5): Clicking this button executes the SQL statements that are currently
selected. If multiple statements exist and none are selected, then all are executed.
Undo: Allows you to undo an unlimited number of edits in the SQL window.
Redo: Allows you to redo previously undone commands. You can step backward and
forward through the undo history using both these commands.
Import SQL file: Opens an SQL file in the SQL Editor, which can then be executed.
Export SQL file: Saves SQL queries for later use.
Open SQL script in DatabaseSpy: Starts DatabaseSpy and opens the script in the
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
517
SQL Editor.
Options: Opens the Options dialog box allowing you to define general database query
settings as well as SQL Editor settings.
Generating SQL Statements
SQL statements can be generated automatically from the Database Browser, loaded from scripts,
or entered manually.
To generate SQL SELECT statements from the Database Browser, do one of the
following:
Click a database object (such as a table or view), or a folder, in the Database Browser
and drag it into the SQL Editor.
Right-click a database object in the Database Browser and select Show in SQL Editor |
Select.
To create SQL statements manually:
1.
Start entering the SQL statement in the SQL Editor. If autocompletion is set to occur
automatically, a drop-down list with suggestions appears while you enter statement.
2.
Use the cursor Up and Down keys to select a suggestion, and then press Enter to insert
the highlighted option (see also SQL Auto-Completion Suggestions).
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
518
Data Sources and Targets
Databases and MapForce
Executing SQL Statements
The SQL statements that appear in the SQL Editor can be executed against the database, with
immediate effect. The result of the SQL query and the number of affected rows is displayed in the
Messages pane of the DB Query pane.
When multiple SQL statements appear in the SQL Editor, only the selected statements will be
executed. You can select individual SQL statements as follows:
Holding the left mouse button clicked, drag the cursor over a specific statement.
Click a line number in the SQL Editor.
Triple-click a specific statement.
To execute a SQL statement:
1.
Enter or select the SQL statement in the SQL Editor (see Generating SQL Statements ).
2.
Click the Execute (
) button.
Importing and Exporting SQL Scripts
You can save any SQL that appears in an SQL Editor window to a file and re-use the script file
later on.
To export the contents of the SQL Editor pane to a file:
Click Export SQL file (
), and enter a name for the SQL script.
To import a previously saved SQL file:
Click Import SQL file (
), and select the SQL file you want to open.
Adding and Removing SQL Comments
The SQL Editor allows you to comment out statements, parts of statements, or groups of
statements. These statements, or the respective parts of them, are skipped when the SQL script
is being executed.
To comment out a section of text:
1.
2.
Select a statement or part of a statement.
Right-click the selected statement and select Insert / Remove Block Comment.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
519
To comment out text line by line:
Right-click at the position you want to comment out the text and select Insert / Remove
Line Comment. The statement is commented out from the current position of the cursor
to the end of the statement.
To remove a block comment or a line comment:
1.
2.
Select the part of the statement that is commented out. If you want to remove a line
comment, it is sufficient to select only the comment marks -- before the comment.
Right-click and select Insert / Remove Block (or Line) Comment.
Using Bookmarks
Bookmarks are used to mark items of interest in long scripts.
To add a bookmark:
Right-click the line you want to have bookmarked and select Insert/Remove Bookmark
from the context menu.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
520
Data Sources and Targets
A bookmark icon
Databases and MapForce
is displayed in the margin at the beginning of the bookmarked line.
To remove a bookmark:
Right-click the line from where you want to remove the bookmark and select Insert/
Remove Bookmark from the context menu.
To navigate between bookmarks:
To move the cursor to the next bookmark, right-click and select Go to Next Bookmark.
To move the cursor to the previous bookmark, right-click and select Go to Previous
Bookmark.
To remove all Bookmarks:
Right-click and select Remove all Bookmarks.
Inserting Regions
Regions are sections of text that you mark and declare as a unit to structure your SQL scripts.
Regions can be collapsed and expanded to display or hide parts of SQL scripts. It is also
possible to nest regions within other regions.
When you insert a region, an expand/collapse icon and a --region comment are inserted above
the selected text.
Note:
You can change the name of a region by appending descriptive text to the --region
comment. The word "region" must not be deleted, e.g. --region DB2query.
To create a region:
1.
2.
In the SQL Editor, select the statements you want to make into a region.
Right-click and select Add Region from the context menu. The selected statements
become a region which can be expanded or collapsed.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
3.
Databases and MapForce
521
Click the + or - box to expand or collapse the region.
To remove a region:
Delete the -- region and -- endregion comments.
7.2.8.3
Browsing Database Objects
When you are connected to one or several databases, the Database Browser pane gives a full
overview of the objects in each database, including tables, views, procedures, and so on, up to the
most detailed level. For databases with XML support, the Database Browser additionally shows
registered XML schemas in a separate folder.
For custom navigation through database objects, the Database Browser pane includes several
predefined database display layouts. The predefined layouts are available in the top area of the
Database Browser.
To select a layout, click the Folders Layout (
) drop-down button and select an entry from
the list. Note that the button changes with the selected layout.
The Folders layout organizes database objects into folders based on object type in a
hierarchical tree, this is the default setting.
The No Schemas layout is similar to the Folders layout, except that there are no
database schema folders; tables are therefore not categorized by database schema.
The No Folders layout displays database objects in a hierarchy without using folders.
The Flat layout divides database objects by type in the first hierarchical level. For
example, instead of columns being contained in the corresponding table, all columns are
displayed in a separate Columns folder.
The Table Dependencies layout categorizes tables according to their relationships with
other tables. There are categories for tables with foreign keys, tables referenced by
foreign keys and tables that have no relationships to other tables.
In addition to layout navigation, you can use the Database Browser for the following tasks:
Generate SQL statements (see Generating SQL Statements ).
Filter and search the displayed database objects (see Filtering and Searching Database
Objects ).
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
522
Data Sources and Targets
Databases and MapForce
Sort the tables into "System" and "User" tables.
Refresh the root object of the active data source.
To sort tables into User and System tables:
In the Database Browser, right-click the "Tables" folder, and then select Sort into User
and System Tables.
Note: This function is available when one of the following layouts is selected: Folders,
No Schemas or Flat.
To refresh the root object of the active data source:
At the top of the Database Browser, click Refresh (
).
Filtering and Searching Database Objects
You can filter any database objects (schemas, tables, views, etc) displayed in the Database
Browser by name or part of a name. Objects are filtered as you type in the characters. Filtering
is case-insensitive by default. Filtering is not supported if you have selected the "No Folders"
layout.
Filtering database objects
1.
At the top of the Database Browser, click Filter Folder contents (
appear next to all folders in the currently selected layout.
2.
Click the filter icon next to the folder you want to filter, and select the filtering option from
the context menu (for example, Contains).
Altova MapForce 2017 Professional Edition
). Filter icons
© 2017 Altova Gmb H
Data Sources and Targets
3.
Databases and MapForce
523
In the empty field which appears next to the filter icon, enter the search text (for example,
"G"). The results are adjusted as you type.
Searching database objects
To find a specific database item by its name, you can either use filtering functions or the Object
Locator. To find database elements using the Object Locator:
1.
2.
At the top of the Database Browser, click Object Locator (
).
In the drop-down list that appears, enter the search text (for example, "Off").
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
524
Data Sources and Targets
3.
Databases and MapForce
Click an object in the list to select it in the Database Browser.
Context Options in Database Browser
The context menu options available in the Database Browser depend on the object you have
selected, for example:
Right-clicking the "root" object allows you to Refresh the database.
Right-clicking a folder always presents the same choices: Expand | Siblings | Children
and Collapse | Siblings | Children.
Right-clicking a database object reveals the Show in SQL Editor command and the
submenu items discussed below.
To select multiple database objects, press either Shift + Click or Ctrl + Click.
Note:
The syntax of the SQL statements may vary depending on the database you are using.
The syntax below applies to Microsoft SQL Server 2014.
The following options are available under the Show in SQL Editor context menu for the root
object:
CREATE: Creates a CREATE statement for the selected database root object, for
example:
CREATE DATABASE [MYDB]
DROP: Creates a DROP statement for the selected database root object, for example:
DROP DATABASE [MYDB]
The following options are available under the Show in SQL Editor context menu for tables and
views:
SELECT: Creates a SELECT statement that retrieves data from all columns of the source
table, for example:
SELECT [DepartmentID], [Name], [GroupName], [ModifiedDate] FROM
[MYDB].[HumanResources].[Department]
Name: Returns the name of the table.
Path: Returns the full path of the tables, in the format
DataSourceName.DatabaseName.SchemaName.TableName.
If you selected multiple tables, the names or paths are printed on separate lines, separated
by commas.
The following options are available under the Show in SQL Editor context menu for columns:
SELECT: Creates a SELECT statement that retrieves data from the selected column(s)
of the parent table, for example:
SELECT [DepartmentID] FROM [MYDB].[HumanResources].[Department]
Name: Returns the name of the selected column.
Path: Returns the full path of the column, in the format
DataSourceName.DatabaseName.SchemaName.TableName.ColumnName.
If you selected multiple columns, the names or paths are printed on separate lines, separated
by commas.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
525
The following options are available under the Show in SQL Editor context menu for constraints:
Name: Returns the name of the selected constraint.
Path: Returns the full path of the constraint, in the format
DataSourceName.DatabaseName.SchemaName.TableName.ConstraintName.
If you selected multiple constraints, the names or paths are printed on separate lines,
separated by commas.
The following options are available under the Show in SQL Editor context menu for indexes:
Name: Returns the name of the selected index.
Path: Returns the full path of the index, in the format
DataSourceName.DatabaseName.SchemaName.TableName.IndexName.
If you selected multiple indexes, the names or paths are printed on separate lines, separated
by commas.
If the database has support for XML Schemas, the following options are available for every schema
displayed under the "XML Schemas" folder:
View in XMLSpy: Opens the database schema in XMLSpy, provided that the latter is
installed.
Manage XML Schemas: Opens a dialog box where you can add new or drop existing
database XML schemas.
7.2.8.4
Copying, Sorting, and Searching the Query Results
The Results tab of the DB Query pane shows the recordset retrieved as a result of a database
query.
The toolbar buttons enable navigation between results and SQL statements and facilitate
searching within the query results.
Find: Searches a specific text within the displayed results. Press F3 to go to the next
occurrence of the search term.
Go to statement: Jumps to the SQL Editor and highlights the SQL statement that
produced the current result. This might be particularly useful when the SQL Editor
contains multiple statements.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
526
Data Sources and Targets
Databases and MapForce
To select cells from the query results:
Click a column header to select the entire column
Click a row number to select the entire row
Click individual cells. Holding down the Ctrl key while clicking allows you to make
multiple selections. If a column or cell contains XML data then this data can also be
copied.
Note: The context menu can also be used to select data, Selection | Row | Column |
All.
To copy the selected cells to clipboard:
Right-click and select Copy selected cells from the context menu.
To sort data:
Right-click anywhere in the column to be sorted and select Sorting | Ascending or
Descending
Click the sort icon in the column header
The data is sorted according to the contents of the sorted column.
To restore the default sort order:
Right-click anywhere in the table and choose Sorting | Restore default from the context
menu.
7.2.8.5
Viewing the Status of Executed Queries
The Messages tab of the DB Query pane provides specific information about the last executed
SQL statement and reports errors or warning messages.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
527
You can use different filters to customize the view of the Messages tab or use the Next and
Previous buttons to browse data row by row. The buttons at the top are used to navigate the
messages, copy text to clipboard, and hide certain parts of the message. These options are also
available in the context menu, when you right-click anywhere inside the Messages tab.
Filter: Opens a pop-up menu from where you can filter out the individual message types
(Summary, Success, Warning, Error, Autoinsertion, Progress). "Autoinsertion"
refers to those messages that may be triggered when SQL statements or SQL
constructs are inserted automatically in SQL Editor. "Progress" messages report the
database connection result, as well as the outcome of SQL parsing and data structure
loading.
You can check all or none of these options with a single mouse click by selecting
either Check All or Uncheck All from the pop-up menu.
Next: Jumps to and highlights the next message.
Previous: Jumps to and highlights the previous message.
Copy selected message to the clipboard
Copy selected message including its children to the clipboard
Copy all messages to the clipboard
Find: Opens the Find dialog box.
Find previous: Jumps to the previous occurrence of the string specified in the Find
dialog box.
Find next: Jumps to the next occurrence of the string specified in the Find dialog box.
Clear: Removes all messages from the Message tab of the SQL Editor window.
7.2.8.6
Database Query Settings
This section includes information about configuring miscellaneous settings applicable to SQL
statements entered or loaded in SQL Editor, as well as the query results displayed after a query
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
528
Data Sources and Targets
Databases and MapForce
is executed.
SQL File Encoding Settings
You can specify the encoding options for SQL files created or opened with SQL Editor as follows:
1.
Click the DB Query tab.
2.
At the top of the pane, click Options
, and then click General | Encoding.
Default encoding for new SQL files
Define the default encoding for new files so that each new document includes the
encoding specification that you specify here. If a two- or four-byte encoding is selected as
the default encoding (for example, UTF-16, UCS-2, or UCS-4), you can also choose
between little-endian and big-endian byte ordering for the SQL files.
The encoding of existing files is not affected by this setting.
Open SQL files with unknown encoding as
You can select the encoding with which to open an SQL file with no encoding
specification or where the encoding cannot be detected.
Note:
SQL files which have no encoding specification are saved with a UTF-8 encoding.
SQL Editor General Settings
You can change the general settings applicable to the SQL Editor as follows:
1.
Click the DB Query tab.
2.
At the top of the pane, click Options
Altova MapForce 2017 Professional Edition
, and then click SQL Editor.
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
529
General
Syntax coloring emphasizes different elements of SQL syntax using different colors.
Activate the Connect datasource on execute check box to connect to the
corresponding data source automatically whenever a SQL statement is executed and its
data source is not connected.
Retrieval
Specify the maximum amount of time permissible for SQL execution (Execution timeout)
in seconds.
Activating the Show timeout dialog check box allows you to change the time-out
settings when the permissible execution period is exceeded.
Entry Helper Buffer
To enable auto-completion suggestions as you start typing SQL statements, select the
Automatically open check box (see also Auto-Completion).
The entry helper buffer for auto-completion can be filled either when you connect to a data
source or when it is used for the first time. Note that filling the buffer may take some time.
Use the Clear Buffer button to reset the buffer.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
530
Data Sources and Targets
Databases and MapForce
Text View Settings
Allows you to define the specific Text view settings: Margins, Tabs, Visual aids, as well
as showing you the Text view navigation hotkeys.
SQL Statement Generation Settings
You can specify the SQL statement generation syntax for various database kinds as follows:
1.
Click the DB Query tab.
2.
At the top of the pane, click Options
, and then click SQL Editor.
To define the syntax preferences for a specific database, select it from the list, and then enable or
disable the three check boxes to the right.
To define a unique syntax for all databases, select Apply to all databases, and then enable or
disable the three check boxes to the right. Note that using common settings for all databases
may cause inability to edit data in Oracle and IBM DB2 and iSeries databases via a JDBC
connection.
Query Result View Settings
You can configure the appearance of the Results tab of the DB Query pane as follows:
1.
Click the DB Query tab.
2.
At the top of the pane, click Options
Altova MapForce 2017 Professional Edition
, and then click SQL Editor | Result View.
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
531
Select the Show grid with alternating colors check box to display rows in Result tabs as
simple grid or with alternating white and colored rows. The alternating color is configurable.
The Display Options group lets you define how horizontal and vertical grid lines, as well as line
numbers and the Result toolbar, are displayed. You can switch any of these options off by
deactivating the respective check box.
The Data Editing group lets you define the transaction settings, if the cells are to be filled with
default values and if a hint is to be displayed when data editing is limited.
SQL Editor Font Settings
You can configure color and font settings of SQL statements that appear in SQL Editor as follows:
1.
Click the DB Query tab.
2.
At the top of the pane, click Options
© 2017 Altova Gmb H
, and then click SQL Editor | Fonts.
Altova MapForce 2017 Professional Edition
532
Data Sources and Targets
Databases and MapForce
The font settings listed in the Font Settings list box are elements of SQL statements. You can
choose the common font face, style, and size of all text that appears in SQL Editor. Note that the
same font and size is used for all text types.
Only the style can be changed for individual text types. This enables the syntax coloring feature.
Click the Reset to default button to restore the original settings.
7.2.9
Stored Procedures
Stored procedures are programs that are hosted and run on a database server. Stored procedures
can be called by client applications and they are often written in some extended dialect of SQL.
Some databases support also implementations in Java, .NET CLR, or other programming
languages.
Typical uses of stored procedures include querying a database and returning data to the calling
client, or performing modifications to the database after additional validation of input parameters.
Stored procedures can also perform other actions outside the database, e.g. send e-mails.
Stored procedures in MapForce:
Can be present (and called) in both source and target database components.
Can have data be mapped to them by input parameters, as well as mapped from them, by
output parameters.
Can be inserted as a function-like call. This allows you to provide input data, execute the
stored procedure, and read/map the output data to other components.
Are visible with their unique name and a clickable button, inside the database component
once the database has been inserted into the mapping area.
Cannot be edited from within MapForce
Can only be used in the BUILT-IN execution engine. Code generation in C++, C#, or Java
is not supported.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Note:
Databases and MapForce
533
To illustrate how MapForce implements stored procedures, this section uses Microsoft
SQL Server 2008 and the "AdventureWorks" database. The latter can be downloaded from
the CodePlex website ( http://sqlserversamples.codeplex.com ) .
Stored procedure support
Input/output parameter types: user-defined types, cursor types, variant types and many
"exotic" database-specific data types (e.g. arrays, geometry, CLR types, etc.) are
generally not supported.
Procedure and function overloading (multiple definitions of routines with the same name
and different parameters) is not supported.
Some databases support default values on input parameters, this is currently not
supported. You cannot omit input parameters in the mapping to use the default value.
Stored procedures returning multiple recordsets are supported depending on the
combination of driver and database API (ODBC/ADO/JDBC). Only procedures that return
the same number of recordsets with a fixed column structure are supported.
Stored procedures in Microsoft Access databases have very limited functionality and are
not supported in MapForce.
Drivers
Whenever possible, use the latest version of the database native driver maintained by the
database vendor. Avoid using bridge drivers, such as ODBC to ADO Bridge, or ODBC to
JDBC Bridge.
Firebird 2.5
Supported in MapForce: stored procedures, table-valued functions
IBM DB2 8, 9, 10, IBM DB2 for i 6.1, 7.1
Supported in MapForce: stored procedures, scalar functions, table-valued functions.
Row-valued functions (RETURNS ROW) are not supported.
It is recommended to install at minimum "IBM_DB2 9.7 Fix Pack 3a" to avoid a confirmed
JDBC driver issue when reading errors/warnings after execution. This also fixes an issue
with the ADO provider that causes one missing result set row.
Informix 11.7
Supported in MapForce: stored procedures, table-valued functions.
Microsoft SQL Server 2005, 2008, 2012, 2014
Supported in MapForce: stored procedures, scalar functions, table-valued functions.
It is recommended to use the latest SQL Server Native Client driver instead of the
Microsoft OLE DB Provider for SQL Server.
The ADO API has limited support for some data types introduced with SQL Server 2008
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
534
Data Sources and Targets
Databases and MapForce
(datetime2, datetimeoffset). If you encounter data truncation issues with these
temporal types when using ADO with the SQL Server Native Client, you can set the
connection string argument DataTypeCompatibility=80 or use ODBC.
MySQL 5.5, 5.6
Supported in MapForce: stored procedures, scalar functions
MySQL includes complete support for stored procedures and functions starting with
version 5.5. If you are using an earlier version, functionality in MapForce is limited.
Oracle 9i, 10g, 11g, 12c
Supported in MapForce: stored procedures, scalar functions, table-valued functions.
It is recommended to use a native Oracle driver instead of the Microsoft OLE DB
Provider for Oracle.
Oracle has a special way to return result sets to the client by using output parameters of
type REF CURSOR. This is supported by MapForce for stored procedures, but not for
functions. The names and number of recordsets is therefore always fixed for Oracle
stored procedures.
PostgreSQL 8, 9
Supported in MapForce: scalar functions, row-valued functions, table-valued functions.
In PostgreSQL, any output parameters defined in a function describe the columns of the
result set. This information is automatically used by MapForce - no detection by
execution or manual input of recordsets is needed. Parameters of type refcursor are not
supported.
Progress OpenEdge 11.6
Supported in MapForce: stored procedures.
7.2.9.1
Inserting stored procedures in database components
Stored procedures can be incorporated into a database component when inserting it into the
mapping area. This follows the usual sequence of inserting a database component into MapForce.
To insert a database component containing stored procedures:
1.
2.
3.
Click the Insert Database icon, or select the menu option File | Insert Database.
Use the Connection Wizard to connect to the database.
Having filled in the Connection tab of the Data Link Properties dialog box, click the OK
button.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
4.
Click the expand button to select the database tables you want to insert, and select the
specific tables.
5.
Click the expand button of the Procedures folder to select the stored procedures that you
want to insert along with the tables, then click OK.
535
The database component is inserted and shows the selected tables followed by the stored
procedures that you selected.
Tables, views and procedures are sorted alphabetically in the database component.
Each stored procedure is shown as an item in the database component containing the
procedure name and a clickable button. The button allows you to select if the procedure
is to be used as a source or target, as well as other procedure settings.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
536
Data Sources and Targets
Databases and MapForce
At this point, MapForce has no specific information if the parameters of the stored
procedure are to be used as source or target parameters. This is achieved by clicking the
stored procedure button and selecting the specific option.
7.2.9.2
Use cases
The following uses cases should cover most common types of stored procedures and how to
define them in MapForce.
I want to:
Read this section
I want to call a stored procedure to retrieve
data from a database and map it to another
component.
Stored procedures in Source components
E.g. I want to use a stored procedure as a
data source to write the resulting data into
another file (XML, TXT, EDI, etc.).
I want to call a stored procedure to modify the Stored procedures in Target components
database or perform another specific action.
I want to use stored procedures to generate
one or more values/keys for an Insert
statement in the same database.
7.2.9.3
Using stored procedures to generate primary
keys
Stored procedures and local relations
By using local relations (see Defining Local Relationships), you can define a hierarchical order in
which to call stored procedures or perform actions (insert, update, ...) on database tables. They
can be used in source and target components.
A local relation always has a parent object (containing a primary/unique key) and a child object
(containing a foreign key).
Possible parent objects and their fields used in a relation are:
Database table or view (column)
Stored procedure (output parameter or return value)
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
537
Recordset of a stored procedure (column) - only for source and procedure call
components
User-defined SELECT statement (column)
Possible child objects and their fields are:
Database table or view (column, produces a WHERE condition)
Stored procedure (input parameter)
User-defined SELECT statement (input parameter)
In source components, this makes it easy to read data from related objects, e.g. read IDs from a
database table and call a stored procedure with each of these IDs to retrieve related information. It
is also possible to call a stored procedure with data retrieved from another procedure.
In target components, local relations allow defining a clear order in which multiple related
procedures are to be called, e.g. one that creates an ID value, and another that inserts related
information into another table. It is also possible to mix stored procedures and tables in local
relations, e.g. perform the insert directly on the related table instead of calling another procedure.
7.2.9.4
Stored procedures as a data source
The output of a stored procedure can be zero or more output or return parameters, and zero or
more recordsets from SELECT statements embedded inside the stored procedure. A recordset or
result set is the output of such a SELECT statement, similar to a table or view. Output
parameters and recordsets can be mapped to target components.
The column structures of these recordsets cannot be directly read from the database catalog,
they must therefore be detected by executing the stored procedure at design time or by being
defined manually - see Defining recordsets for details.
Depending on whether the stored procedure has input parameters or not, the handling in
MapForce is different:
The stored procedure has no input parameters
Stored procedures
without input
parameters
I want to supply the values for the procedure's input parameters by
mapping from an XML, Text, or other type of file, or from mapping input
parameters or constants
Call with
parameters - input
and output
I want to supply the values for the procedure's input parameters from a
table or view in the same database, or from the output of another stored
procedure
Source
components and
Local Relations
Stored procedures without input parameters
Use this option (for example) if you want to use the stored procedure in a source component
without having any input parameters.
E.g. this could be a stored procedure that is a pure SELECT-type query without any input
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
538
Data Sources and Targets
Databases and MapForce
parameters, where you want to map the result of the SELECT statement to a target component.
E.g. HumanResources.uspGetAllEmployees of the AdventureWorks database.
Stored procedure:
PROCEDURE HumanResources.uspGetAllEmployees
AS
SELECT LastName, FirstName, JobTitle, Department
FROM HumanResources.vEmployeeDepartment;
The columns of the recordset cannot be directly read from the database catalog by MapForce,
they must therefore be detected by executing the stored procedure once or by being defined
manually.
Defining the output recordset of a source component:
Having inserted the AdventureWorks database component and selected the HumanResources
tables and included stored procedures:
1.
Click the "stored procedure" button and select the option "Show nodes as Source".
2.
The Return value node is inserted below the stored procedure name. Since we want to
read the recordset and not the return value, click the stored procedure button again and
select Edit RecordSet structures.
Click the "Define input parameters and call procedure" button.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
539
This opens the "Evaluate Stored Procedure" dialog box.
3.
Click the "Execute" button, then click OK.
The recordset fields are now visible in the Recordsets section of the dialog box.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
540
Data Sources and Targets
4.
Databases and MapForce
Click the OK button again to complete the recordset definition.
The columns, LastName etc., are shown as nodes below the recordset node RS1. (Click
the "+" button to expand the recordset if not visible).
Completing the mapping:
1. Insert a Text file component and map the output icons to the text file.
2.
Click the Output button to see the result.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
541
Note:
If executing the stored procedure has side effects (depending on the procedure implementation)
that you want to avoid at design time, recordsets can be also be defined manually in the
Recordset Structures dialog box, by adding recordsets and their associated columns. Click the
Add recordset, or Add column buttons in the Recordset Structures dialog box.
Call with parameters - input and output
Stored procedures can also be used as a function-like call. This allows you to:
provide input data to the procedure
execute the procedure
map the procedure output data to other components
To use a stored procedure as a function-like call:
Having inserted the AdventureWorks database component and selected the Production tables and
included stored procedures:
1.
Click the "stored procedure" button of Production.uspGetList, to open the menu.
2.
Select the option "Insert Call with Parameters".
This inserts the procedure component into the mapping. The component looks and works
similar to a web service, or user-defined, component. The procedure name is
automatically connected to the "procedure" item of the component.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
542
Data Sources and Targets
Databases and MapForce
The procedure input parameters are shown on the left, while the output parameters are
shown at right. This particular stored procedure returns output parameters and also a
recordset, however we must define its structure before we can see and use it in
MapForce:
To define the recordset structure:
1. Click the "stored procedure" button, of uspGetList, and select "Edit recordset structures".
2. Click the "Define input parameters and call procedure" button, then click Execute in the
dialog box that opens.
This writes the returned output parameter values into the table below and displays that
one recordset was retrieved.
3.
Click the OK button to confirm, then click OK to close the Recordset dialog box.
The recordset has been added to the output section of the stored procedure component.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
543
Using the call parameter component:
1. Define the components you want to use to supply the input parameters, e.g. two constant
components as shown in the screen shot, and connect them to the input parameters.
2.
Define and insert the target component which will be used to contain the stored procedure
output, e.g. an XML document as shown below.
3.
Click the Output button to see the result of the mapping.
The various road frame products are listed.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
544
Data Sources and Targets
Databases and MapForce
Source components and Local Relations
Use this option if you want to combine data supplied by a stored procedure recordset with data
from another table, to which there is no direct relationship in the database.
PROCEDURE HumanResources.uspGetAllEmployees
AS
SELECT LastName, FirstName, JobTitle, Department
FROM HumanResources.vEmployeeDepartment;
The columns of the recordset cannot be directly read from the database catalog by MapForce,
they must therefore be detected by executing the stored procedure once or by being defined
manually.
Defining the output recordset of a source component:
Having inserted the AdventureWorks database component and selected the HumanResources
tables and included stored procedures:
1.
Click the "stored procedure" button and select the option "Show nodes as Source".
2.
The Return value node is inserted below the stored procedure name. Since we want to
read the recordset and not the return value, click the stored procedure button again and
select Edit RecordSet structures.
Click the "Define input parameters and call procedure" button.
This opens the "Evaluate Stored Procedure" dialog box.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
3.
Click the "Execute" button, then click OK.
The recordset fields are now visible in the Recordsets section of the dialog box.
4.
Click the OK button again to complete the recordset definition.
The columns, LastName etc., are shown as nodes below the recordset node RS1. (Click
the "+" button to expand the recordset if not visible).
© 2017 Altova Gmb H
545
Altova MapForce 2017 Professional Edition
546
Data Sources and Targets
Databases and MapForce
Defining a Local relation to a different table:
1. Right click the Component header, and select Add/Remove/Edit Database Objects.
2. Click the Add/Edit Relations button to open the Add/Edit Relations dialog box, then click
the "Add Relation" button.
3. Define the Primary/Unique Key Object as the stored procedure
uspGetAllEmployees.RS1 and the column as the @Department parameter.
4. Define the Foreign Key Object as Department and the column as Name.
5.
Click the OK button in the various dialog boxes.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
547
The Department table is now displayed as a child of the stored procedure.
Completing the mapping
1. Insert the target schema to which you want to map the source database data, and add
the connections as shown below.
2.
Click the Output button to see the result.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
548
7.2.9.5
Data Sources and Targets
Databases and MapForce
Stored procedures in Target components
Choose this option when the stored procedure makes changes to the database, e.g. add/update/
delete etc., and you are not interested in any stored procedure output.
To use stored procedures in a target component:
This option adds the child nodes of the input parameters (as well as in/out parameters) under the
stored procedure item in the target database component.
E.g.: You want to add a new product model to the database, using the uspAddProductModel
stored procedure of the AdventureWorks database.
Stored procedure:
PROCEDURE Production.uspAddProductModel
@ModelName nvarchar(50),
@Inst xml
as
INSERT INTO [AdventureWorks].[Production].[ProductModel]
([Name]
--,[CatalogDescription]
,[Instructions]
,[rowguid]
,[ModifiedDate])
VALUES
(@ModelName
--,<CatalogDescription, ProductDescriptionSchemaCollection,>
,@Inst
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
549
,NEWID()
,GETDATE());
At runtime, MapForce executes the stored procedure using all the mapped input parameters
while ignoring the stored procedure data output.
To create the input parameter items in a target component:
Having inserted the AdventureWorks database component and selected the Production tables and
included stored procedures:
1.
2.
Click the "stored procedure" button and select the option "Show nodes as Target".
This inserts the @ModelName and @Inst input parameters below the stored procedure
name. Only the input icons of the input parameters are available in the target
component.
Insert a source component, e.g. text file, XML file, etc., and map the items that are to
supply the input parameter data, to the input icons of the stored procedure.
To define transactions for a stored procedure:
1. Click the "stored procedure" button and select the option "Procedure settings".
This opens the Database Procedure Settings dialog box.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
550
Data Sources and Targets
2.
3.
Databases and MapForce
Click the "Use Transactions" check box and click OK to confirm.
The transaction setting makes sure that the procedure commands can be rolled back if
an error occurs during execution.
Click the Output button to see the commands that will be sent to the database.
This dialog box also allows you to define SQL statements to be executed before the
stored procedure is called.
Notes:
The "Add Duplicate input..." context menu options are disabled for the stored procedure
parameters, as each parameter is an atomic value (and could also be "nullable").
The "Add duplicate input..." context menu options are however available for a stored procedure
item. This would call the stored procedure for each duplicated item/node.
Using stored procedures to generate primary keys
Choose this option when the stored procedure makes changes to a database table, and you also
want to use the procedure output parameter to generate a primary key in a different table.
The uspAddProductModelEx procedure is a variation of the uspAddProductModel stored
procedure in the AdventureWorks database.
procedure Production.uspAddProductModelEx
@ModelName nvarchar(50),
@Inst xml,
@ProductModelID int OUTPUT
as begin
INSERT INTO [AdventureWorks].[Production].[ProductModel]
([Name]
,[Instructions]
,[rowguid]
,[ModifiedDate])
VALUES
(@ModelName
,@Inst
,NEWID()
,GETDATE());
SELECT @ProductModelID = SCOPE_IDENTITY()
end;
Having inserted the AdventureWorks database component, selected the Production tables and
included stored procedures:
1.
Click the "stored procedure" button and select the option "Show nodes as Target".
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
551
This inserts the ModelName and Inst parameters below the procedure name. Only the
input parameters of the stored procedure are visible in the component.
2.
3.
As the Inst parameter is of type XML, we need to assign it a relevant XML Schema to
supply the XML data.
Right click the Inst parameter and select "Assign XML Schema to field...".
Select the provided "Production.ManuInstructionsSchemaCollection in the "Database"
combo box, and click OK.
This adds the XML Schema elements and attributes to the component. The ModelName
parameter and all the Inst parameters are now available in the component.
We now want to define a Local relation to a table that has no direct connection to the
table referenced by the stored procedure parameters (production.product).
Defining a Local relation to a table in which you want to generate a primary
key:
1. Right click the Component header, and select Add/Remove/Edit Database Objects.
2. Click the Add/Edit Relations button to open the Add/Edit Relations dialog box, then click
the "Add Relation" button.
3. Define the Primary/Unique Key Object as the stored procedure uspAddProductModelEx
and the column as the @ProductModelID parameter.
4. Define the Foreign Key Object as ProductModelIllustration and the column as
ProductModelID.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
552
Data Sources and Targets
5.
Databases and MapForce
Click the OK button in the various dialog boxes.
The stored procedure output parameter (ProductModelID) has been added to the stored
procedure as an indicator that it will be used in the local relation, but does not have any
input or output icons.
The table ProductModelIllustration has also been added as a child item to the stored
procedure.
Expanding the table shows the keys and columns of the table. Note that ProductModelID
key shows the stored procedure and parameter name it is related to.
Local relations that use the (output) recordset of the stored procedure, cannot be used
here.
Clicking the stored procedure button and selecting "Procedure Settings" allows you to
define an SQL Statement to be run before the procedure is called, as well as activate
transaction settings.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
Databases and MapForce
553
Defining a transaction for a stored procedure:
1. Click the stored procedure icon and select "Procedure Settings".
2. Click the Use Transactions check box, then click OK to confirm.
Defining the transaction for the stored procedure ensures that both retrieving the key and
inserting the record both occur during the same transaction.
Completing the mapping:
The screenshot below shows only a subset of the data you would normally map.
1.
Map the data source items to the target database; in this case constants.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
554
Data Sources and Targets
2.
Databases and MapForce
Click the Output button to see the pseudo SQL that will be sent to the database.
MapForce automatically calls the stored procedure for each record before the Insert
action.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
7.3
CSV and Text Files
555
CSV and Text Files
MapForce includes support for mapping data to or from text-based file formats such as CSV
(comma-separated values) and FLF (Fixed-Length Field) text files. For example, you can create
data transformations such as:
XML schema to/from flat file formats
Database to/from flat file formats
Note that, in case of CSV, your files can have as delimiter not only commas, but also tabs,
semicolons, spaces, or any other custom values.
In addition to CSV and FLF files, mapping to or from text files with more complex or custom
structures is possible using MapForce FlexText (this module is available in MapForce Enterprise
Edition). FlexText essentially enables you to define the structure of your custom text data (using
a so-called "FlexText template"), for the purpose of mapping it to other formats.
Mapping data to or from text files is supported in any one of the following languages: Java, C#, C+
+, or BUILT-IN.
There are two ways that mapped flat file data can be generated:
By clicking the Output tab which generates a preview using the Built-in execution engine.
You can also save the mapping result by selecting the menu option Output | Save
output file, or clicking the
icon.
By selecting File | Generate code in | Java, C#, or C++ , and then compiling and
executing the generated code.
7.3.1
Example: Mapping CSV Files to XML
The goal of this example is to create a mapping which reads data from a simple CSV file and
writes it to an XML file. The files used in the example are available in the <Documents>\Altova
\MapForce2017\MapForceExamples\Tutorial\ folder.
1.
2.
3.
Select one of the following as transformation language: Java, C#, C++, or BUILT-IN.
Add a Text file component to the mapping area (on the Insert menu, click Text File, or
click the Insert Text file toolbar button (
).
On the Component Settings dialog box, click Input file and browse for the
Altova_csv.csv file. The file contents are now visible in the lower part of the dialog box.
Note that only the first 20 rows of the text file are displayed when in preview mode.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
556
Data Sources and Targets
CSV and Text Files
4.
Click inside the Field1 header and change the text to First-name. Do the same for all the
other fields, as follows: Field 2 => Last-name, Field 3 =>Tel-extension, Field 4 => Email,
Field 5 => Position. TIP: Press the Tab key to cycle through all the fields: header1,
header2 etc.
5.
6.
Click OK.
When prompted to change the component name, click "Change component name". The
CSV component is now visible in the mapping.
Add MFCompany.xsd as the target XML component of the mapping (on the Insert
menu, click XML/Schema file).
Click Skip when prompted to supply a sample XML file, and select Company as the root
element.
Map the corresponding items of both components, making sure to map the Rows item to
the Person item in the schema target.
7.
8.
9.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
CSV and Text Files
557
The connector from the Rows item in the CSV component to the Person item in the
schema is essential, as it defines which elements will be iterated through. That is, for
each row in the CSV file, a new Person element will be created in the XML output
file.
10. Click the Output tab to see the result.
The data from the CSV file is now successfully mapped to an XML file.
7.3.2
Example: Iterating Through Items
This example illustrates how to create iterations (multiple rows) in a target CSV file. The mapping
design file accompanying this example is available at the following path: <Documents>\Altova
\MapForce2017\MapForceExamples\Tutorial\Tut-xml2csv.mfd.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
558
Data Sources and Targets
CSV and Text Files
Tut-xml2csv.mfd
This mapping has been intentionally created as incomplete. If you attempt to validate the example
file using the menu command File | Validate Mapping, you will notice that validation warnings
occur. Also, if you preview the mapping output, a single row is produced, which may or may not
be your intended goal.
Let's assume that your goal is to create multiple rows in the CSV file from a sequence of items in
the XML file. You can achieve this by drawing a connection to the Rows item of the target CSV file.
For example, to iterate through all offices and have the output appear in the CSV file, it is
necessary to connect Office to Rows. By doing this, you are instructing MapForce: for each
Office item of the source XML, create a row in the target CSV file.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
CSV and Text Files
559
The Rows item in the CSV component acts as an iterator for the sequence of items connected to
it. Therefore, if you connect the Office item, the output creates a row for each office found in the
source XML.
In a similar fashion, if you connect Department to the Rows item, a row will be produced for each
department found in the source XML.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
560
Data Sources and Targets
CSV and Text Files
The output would then look as follows:
Finally, mapping Person to the Rows item results in all the Persons being output. In this case,
MapForce will iterate through the records as follows: each Person within each Department, within
each Office.
7.3.3
Example: Creating Hierarchies from CSV and Fixed-Length Text Files
This example is available at the following path: <Documents>\Altova\MapForce2017
\MapForceExamples\Tutorial\Tut-headerDetail.mfd. The example uses a CSV file
(Orders.csv) which has the following format:
Field 1: H defines a header record and D a detail record.
Field 2: A common key for both header and detail records.
Each Header or Detail record is on a separate line.
The contents of the Orders.csv file are shown below.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
CSV and Text Files
561
The aim of the mapping is as follows:
Map the flat file CSV to an hierarchical XML file
Filter the Header records, designated with an H
Associate the respective detail records, designated with a D, with each of the header
records.
tut-headerDetail.mfd
For this to be achieved, the header and detail records must have one common field. In this case
the common field, or key, is the second field of the CSV file, i.e. OrderNo. In the CSV file, both
the first header record and the following two detail records contain the common value 111.
The Orders.csv file has been inserted twice to make the mapping more intuitive.
The Tut-headerDetail.xsd schema file has a hierarchical structure: Order is the root element,
with Header as its child element, and Detail being a child element of Header.
The first Orders.csv file supplies the Header records (and all mapped fields) to the Header item in
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
562
Data Sources and Targets
CSV and Text Files
the schema target file. The filter component is used to filter out all records other than those
starting with H. The Rows item supplies these filtered records to the Header item in the schema
file.
The second Orders.csv file supplies the Detail records (and all mapped fields) by filtering out the
Detail records that match the OrderNo key of the Header record. This is achieved by:
Comparing the OrderNo field of the Header record with the same field of the Detail
records, using the equal function (the priority context is set on the a parameter for
enhanced performance).
Using the Logical-and function to only supply those Detail records containing the same
OrderNo field, as the Header record.
The Rows item supplies these filtered records to the Header and Detail items in the schema file,
through the on-true parameter of the filter component.
Clicking the Output tab produces the XML file displayed below. Each Header record contains its
data, and all associated Detail records that have the same Order No.
Let's now have a look at another example, which uses a slightly different CSV file and is available
in the <Documents>\Altova\MapForce2017\MapForceExamples\Tutorial\ folder as Headdetail-inline.mfd. The difference is that:
No record designator (H, or D) is available
A common key field, the first field of the CSV file, still exists for both header and detail
records (Head-key, Detail-key...). The field is mapped to OrderNo in the schema target
Header and all respective Detail fields are all on the same line.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
CSV and Text Files
563
The mapping has been designed as follows:
The key fields are mapped to the respective OrderNo items in the schema target.
The Detail item in the schema target file has been duplicated, and is displayed as Detail
(2). This allows you to map the second set of detail records to the correct item.
The result of this mapping is basically the same XML file that was produced in the first
example.
Head-detail-inline.mfd
7.3.4
Setting the CSV Options
After you add a text component to the mapping area, you can configure the settings applicable to
it from the Component Settings dialog box. You can open the Component settings dialog box in
one of the following ways:
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
564
Data Sources and Targets
CSV and Text Files
Select the component and, on the Component menu, click Properties.
Double-click the component header.
Right-click the component header, and then click Properties.
Text Component Settings dialog b ox (in CSV mode)
The available settings are as follows.
Component name
The component name is automatically generated when you
create the component. You can however change the name at
any time.
If the component name was automatically generated and you
select an instance file after that, MapForce will prompt you to
optionally update the component name as well.
The component name can contain spaces and full stop
characters. The component name may not contain slashes,
backslashes, colons, double quotes, leading or trailing
spaces. In general, be aware of the following implications
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
CSV and Text Files
565
when changing the name of the component:
If you intend to deploy the mapping to FlowForce
Server, the component name must be unique.
It is recommended to use only characters that can
be entered at the command line. National characters
may have different encodings in Windows and at the
command line.
Input file
Specifies the file from which MapForce will read data. This
field is meaningful for a source component and is filled when
you first create the component and assign to it a text file. The
field can remain empty if you are using the text file
component as a target for your mapping.
In a source component, MapForce uses the value of this field
to read column names and preview the contents of the
instance text file.
To select a new file, click Input File.
Output file
Specifies the file to which MapForce will write data. This field
is meaningful for a target component.
To select a new file, click Output File.
Save all file paths relative to
MFD file
When this option is enabled, MapForce saves the file paths
displayed on the Component Settings dialog box relative to
the location of the MapForce Design (.mfd) file. This setting
affects the input and output files used by the text component.
See also Using Relative Paths on a Component.
Input / Output Encoding
Allows you specify the following settings of the output
instance file:
Encoding name
Byte order
Whether the byte order mark (BOM) character
should be included.
By default, any new components have the encoding defined
in the Default encoding for new components option. You
can access this option from Tools | Options, General tab.
Field delimiter
CSV files are comma delimited "," by default. This option
enables you to select the Tab, Semicolon, or Space
characters as delimiters. You can also enter a custom
delimiter in the Custom field.
First row contains field names
Select this option to instruct MapForce to treat the values in
the first record of the text file as column headers. The column
headers then appear as item names on the mapping.
Treat empty fields as absent
When this option is enabled, empty fields in the source file
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
566
Data Sources and Targets
CSV and Text Files
will not produce a corresponding empty item (element or
attribute) in the target file.
For example, the CSV record "General outgassing
pollutants,,,," consists of four fields, the last three of
which are empty.
Assuming that the output is an XML file, when this option is
disabled, the empty fields will be created in the output with
an empty value (in this example, the elements Last, Title,
and Email):
When this option is enabled, the empty fields will not be
created in the output:
Quote character
If your input file contains quotes around field values, select
the quote character that exists in the source file. The same
setting will also be used for output files.
For output files, you can specify additional settings:
Add when needed
Adds the selected quote character to only those
fields where the text contains the field delimiter, or
line breaks.
Add always
Adds the selected quote character to all fields of
the generated CSV file.
CSV / Fixed
Changes the component type to either CSV or FLF (fixedlength field).
Preview area
The lower part of the dialog box displays a preview of up to 20
rows of the file selected as input or output.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
CSV and Text Files
567
If necessary, you can create the structure of the file (or
change the structure of the existing one), as follows.
Append field
Creates a new field after the last CSV record.
Insert field
Creates a new field immediately before the
currently selected CSV record.
Remove field
Deletes the currently selected field.
<<
Moves the currently selected field one position to
the left.
>>
Moves the currently selected field one position to
the right.
To change the name of a field, click the header (for example,
Field1), and type the new value. Note that the field names
are not editable when the First row contains field names
option is enabled.
To change the data type of a field, select the required value
from the drop-down list. MapForce checks the data type, so if
the input data and the field format to do not agree, then the
data is highlighted in red.
The field types are based on the default XML schema data
types. For example, the Date type is in the form YYYY-MMDD.
7.3.5
Example: Mapping Fixed-Length Text Files to Databases
This example illustrates a data mapping operation between a fixed-length text file (FLF) text file
and a Microsoft Access database. The files used in the example are available in the
<Documents>\Altova\MapForce2017\MapForceExamples\Tutorial\ folder. Both the source
text file and the target database store a list of employees. In the source file, the records are
implicitly delimited by their size, as follows:
Field position and name
Size (in characters)
Field 1 (First name)
8
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
568
Data Sources and Targets
CSV and Text Files
Field position and name
Size (in characters)
Field 2 (Last name)
10
Field 3 (Phone extension)
3
Field 4 (Email)
25
Field 5 (Position)
25
The goals of the mapping is to update the phone extension of each employee in the database to
the one existing in the source file, while adding the prefix "100" to each extension. To achieve the
goal, take the following steps:
Step 1:
Step 2:
Step 3:
Step 4:
Insert and configure the text component
Insert the database component
Design the mapping
Run the mapping
Step 1: Insert and configure the text component
1.
2.
Select the menu option Insert | Text file, or click the insert Text file icon
.
Click the Input file button and select the file <Documents>\Altova\MapForce2017
\MapForceExamples\Tutorial\Altova-FLF.txt file. You will notice that the file is made
up of a single string, and contains fill characters of type #.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
3.
CSV and Text Files
569
Select Fixed.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
570
Data Sources and Targets
CSV and Text Files
4.
Uncheck the Assume record delimiters present check box.
5.
The three rows highlighted in yellow are editable, and enable you to specify i) the field
name ii) the data type and iii) the field size. Type 8 as the new field size, and press
Enter. More data is now visible in the first column, which is now defined as 8 characters
wide.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
CSV and Text Files
6.
Click Append Field to add a new field, and set the length of the second field to 10
characters.
7.
Use the same method to create three more fields of the following lengths: 3, 25, and 25
characters, and change the field headers to make them easier to map: First, Last, Tel.Ext, Email, Title. The preview will then look like this:
8.
In the Fixed Length Field Settings group, select Custom, and type the hash (#) character.
This instructs MapForce to treat the # character as fill character.
9.
Click OK.
© 2017 Altova Gmb H
571
Altova MapForce 2017 Professional Edition
572
Data Sources and Targets
CSV and Text Files
10. Click Change component name. The Text file component appears in the Mapping
window. Data can now be mapped to and from this component.
Step 2: Insert the database component
1.
2.
3.
Select the menu command Insert | Database, select Microsoft Access, and then click
Next.
Select the altova.mdb database available in the <Documents>\Altova\MapForce2017
\MapForceExamples\Tutorial\ folder, and click Connect.
Select the Person table and click OK.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
CSV and Text Files
573
Step 3: Design the mapping
1.
2.
Drag the core | concat function from the Libraries window into the mapping.
Select the menu command Insert | Constant, select Number as type, and enter 100 as
value. This constant stores the new telephone extension prefix.
3.
Create the mapping as shown below.
4.
5.
On the database component, click the Table Action button
next to Person.
Next to Action on input data, select Update If, and ensure that the action for First and
Last fields is set to equal. This instructs MapForce to update the Person table only if
the first and last name in the source file is equal to the corresponding database field.
When this condition is true, the action taken is defined by the mapping. In this case, the
telephone extension is prefixed by 100, and copied to the PhoneExt field of the Person
table.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
574
Data Sources and Targets
CSV and Text Files
Step 4: Run the mapping
To generate the SQL statement (for preview in MapForce), click the Output tab. To run the
SQL statements against the database, click the Run SQL-script button
7.3.6
.
Setting the FLF Options
After you add a text component to the mapping area, you can configure the settings applicable to
it from the Component Settings dialog box. You can open the Component settings dialog box in
one of the following ways:
Select the component and, on the Component menu, click Properties.
Double-click the component header.
Right-click the component header, and then click Properties.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
CSV and Text Files
575
Text Component Settings dialog b ox (in fixed-length field mode)
The available settings are as follows.
Component name
The component name is automatically generated when you
create the component. You can however change the name at
any time.
If the component name was automatically generated and you
select an instance file after that, MapForce will prompt you to
optionally update the component name as well.
The component name can contain spaces and full stop
characters. The component name may not contain slashes,
backslashes, colons, double quotes, leading or trailing
spaces. In general, be aware of the following implications
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
576
Data Sources and Targets
CSV and Text Files
when changing the name of the component:
If you intend to deploy the mapping to FlowForce
Server, the component name must be unique.
It is recommended to use only characters that can
be entered at the command line. National characters
may have different encodings in Windows and at the
command line.
Input file
Specifies the file from which MapForce will read data. This
field is meaningful for a source component and is filled when
you first create the component and assign to it a text file. The
field can remain empty if you are using the text file
component as a target for your mapping.
In a source component, MapForce uses the value of this field
to read column names and preview the contents of the
instance text file.
To select a new file, click Input File.
Output file
Specifies the file to which MapForce will write data. This field
is meaningful for a target component.
To select a new file, click Output File.
Save all file paths relative to
MFD file
When this option is enabled, MapForce saves the file paths
displayed on the Component Settings dialog box relative to
the location of the MapForce Design (.mfd) file. This setting
affects the input and output files used by the text component.
See also Using Relative Paths on a Component.
Input / Output Encoding
Allows you specify the following settings of the output
instance file:
Encoding name
Byte order
Whether the byte order mark (BOM) character
should be included.
By default, any new components have the encoding defined
in the Default encoding for new components option. You
can access this option from Tools | Options, General tab.
Fill Character
This option allows you to define the characters that are to be
used to complete, or fill in, the rest of the (fixed) field when
the incoming data is shorter than the respective field
definitions. The custom field allows you to define your own fill
character in the Custom field.
If the incoming data already contains specific fill characters,
and you enter the same fill character in the Custom field,
then the incoming data will be stripped of those fill
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
CSV and Text Files
577
characters!
Assume record delimiters
present
This option is useful when you want to read data from a
source flat file that does not contain record delimiters such
as CR/LF, or when you want to produce a target flat FLF file
without record delimiters.
See the Understanding the "Assume record delimiters
present" option section below.
Treat empty fields as absent
When this option is enabled, empty fields in the source file
will not produce a corresponding empty item (element or
attribute) in the target file.
Assuming that the output is an XML file, when this option is
disabled, the empty fields will be created in the output with
an empty value (in this example, the elements Last, Title,
and Email):
When this option is enabled, the empty fields will not be
created in the output:
CSV / Fixed
Changes the component type to either CSV or FLF (fixedlength field).
Preview area
The lower part of the dialog box displays a preview of up to 20
rows of the file selected as input or output.
If necessary, you can create the structure of the file (or
change the structure of the existing one), as follows.
© 2017 Altova Gmb H
Append field
Creates a new field after the last record.
Insert field
Creates a new field immediately before the
currently selected record.
Remove field
Deletes the currently selected field.
<<
Moves the currently selected field one position to
the left.
>>
Moves the currently selected field one position to
the right.
Altova MapForce 2017 Professional Edition
578
Data Sources and Targets
CSV and Text Files
To change the name of a field, click the header (in this
example, Field1), and type the new value.
To change the data type of a field, select the required value
from the drop-down list. MapForce checks the data type, so if
the input data and the field format to do not agree, then the
data is highlighted in red.
To set the size of the field in characters, enter the field size
in the third row from the top.
Understanding the "Assume record delimiters present" option
To better understand this option, open the Altova-FLF.txt file available in the <Documents>
\Altova\MapForce2017\MapForceExamples\Tutorial\ folder. Notice that the file consists of 71character long records, without any delimiters such as CR/LF. If you would need to read data from
this particular file, first you would need to split this file into records. That is, create several fields
whose total size sums up to 71 characters (as shown below), and then disable Assume record
delimiters present. For a step-by-step example, see Example: Mapping Fixed-Length Text Files
to Databases.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
CSV and Text Files
579
If you would need to write data from this file to a destination file which uses the same structure,
then enabling Assume record delimiters present creates a new record after every 71
characters.
The mapping result when "Assume record delimiters present "is enab led
If Assume record delimiters present is disabled, the mapping result appears as one long
string.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
580
Data Sources and Targets
CSV and Text Files
The mapping result when "Assume record delimiters present "is disab led
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Data Sources and Targets
7.4
HL7 Version 3
581
HL7 Version 3
Support for HL7 version 3.x is automatically included in MapForce 2017 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 Libraries page of the Altova website ( http://www.altova.com/components_mapforce.html )
Select the Custom Setup in the installer, to only install the HL7 V3 components and XML
Schemas.
Location of HL7 XML Schemas after installation:
32-bit MapForce on 32-bit
operating system,
or
64-bit MapForce on 64-bit
operating system
C:\Program Files\Altova\Common2017\Schemas\hl7v3
32-bit MapForce on 64-bit
operating system
C:\Program Files(x86)\Altova\Common2017\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, database or other components.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
Chapter 8
Functions
584
Functions
8
Functions
Functions represent a powerful way to transform data according to your specific needs. This
section provides instructions on working with functions (regardless if they are built-in to MapForce,
defined by you, or reused from external sources). Use the following roadmap for quick access to
specific tasks related to functions:
I want to...
Read this topic...
Learn how to work with functions in MapForce
Working with Functions
Create my own functions in MapForce
User-Defined Functions
Add custom XSLT functions to MapForce
Importing Custom XSLT 1.0 or 2.0 Functions
Add custom .NET DLL and Java .class
libraries to MapForce
Importing Custom Java and .NET Libraries
Referencing Java, C# and C++ Libraries
Manually
Write my own Java library for use with
MapForce
Create a Java library
Write my own C# library for use with
MapForce
Create a C# library
Write my own C++ library for use with
MapForce
Create a C++ library
View all built-in MapForce functions, or look
up the description of a specific function.
Function Library Reference
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
8.1
Working with Functions
585
Working with Functions
To use a function in a mapping:
1.
2.
Select the transformation language (see Selecting a transformation language).
Click the required function in the Libraries window and drag it to the mapping area.
To search for a function in the Libraries window:
1.
Start typing the function name in the text box located in the lower part of the Libraries
window.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
586
Functions
Working with Functions
By default, MapForce searches by function name and description text. If you want to
exclude the function description from the search, click the down-arrow and disable the
Include function descriptions option.
To cancel the search, press the Esc key or click
.
To view the data type of a function input or output argument:
1.
2.
Make sure that the Show tips
toolbar button is enabled.
Move your mouse over the argument part of a function.
To view the description of a function:
1.
Make sure that the Show tips
Altova MapForce 2017 Professional Edition
toolbar button is enabled.
© 2017 Altova Gmb H
Functions
Working with Functions
2.
587
Move your mouse of the function (this works both in the Libraries pane and on the
mapping area)
To add or delete function arguments (for functions where that is applicable):
Click Add parameter ( ) or Delete parameter (
add or delete, respectively.
Dropping a connection on the
it.
) next to the parameter you want to
symbol automatically adds the parameter and connects
To find all occurrences of a function within the currently active mapping:
Right-click the function name in the Libraries window, and select Find All Calls from the
context menu. The search results are displayed in the Messages window.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
588
8.2
Functions
User-Defined Functions
User-Defined Functions
MapForce allows you to create user-defined functions visually, in the same way as in the main
mapping window.
These functions are then available as function entries in the Libraries window (for example,
"First_Last" in the image below), and are used in the same way as the currently existing
functions. This allows you to organize your mapping into separate building blocks which are
reusable across different mappings.
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 or databases, 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, XML nodes, or databases.
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.
This example uses the Tut-ExpReport.mfd file available in the ...\MapForceExamples\Tutorial\
folder.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
User-Defined Functions
589
Creating user-defined function from existing components
1.
Drag to select both the "concat" and the constant components (you can also hold down
the CTRL key and click the functions individually).
2.
3.
Select the menu option Function | Create User-Defined Function from Selection.
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 ":".
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.
4.
The individual elements that make up the function group appear in a tab with the function
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
590
Functions
User-Defined Functions
name. The new library "user" appears in the Libraries pane with the function name
"First_Last" below it.
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
Opening 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
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
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
User-Defined Functions
591
button
to return to the main mapping. 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 multiple
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
Deleting user-defined functions from a library
1.
2.
Double-click the specific user-defined function in the Libraries window.
Click the Erase button in the top right of the title bar.
Reusing (importing) user-defined functions
User-defined functions defined in one mapping can be imported into any other mapping as follows:
1.
2.
2.
Click the Add/Remove Libraries button at the base of the Libraries window.
Click Add and select the *.mfd file that contains the user-defined function(s) you want to
import. The user-defined function now appears in the Libraries window. The library name
is "user" if you created the user-defined function with the default library name. Otherwise,
look for the library name that you specified when creating the user-defined function.
Drag the imported function from the Libraries window into the mapping.
If the same library name is specified across multiple *.mfd files or custom libraries
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
592
Functions
User-Defined Functions
(see Importing Custom Java and .NET Libraries), functions from all available sources
appear under the same library name in the Libraries window. However, only the
functions in the currently active document can be edited by double-clicking.
Consider the following example:
The function "hello" in the "helloworld" library was imported from a custom library
The function "Join" in the "helloworld" library is a user-defined function defined in the
current *.mfd file
The function "MyUDF" in the "user" library is also a user-defined function defined in the
current *.mfd file
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.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
User-Defined Functions
593
Notes:
The 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.
8.2.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
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
594
Functions
User-Defined Functions
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
specific value from the input sequence.
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.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
User-Defined Functions
595
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.
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 is 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
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
596
Functions
User-Defined Functions
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.
8.2.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
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
User-Defined Functions
597
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
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" check
box.
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.
8.2.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.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
598
Functions
User-Defined Functions
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:
1.
2.
Select the menu option Function | Create User-defined function.
Enter the name of the function e.g. LookupArticle.
3.
Uncheck the "Inlined use" check box and click OK to confirm
A tab only containing only one item, an output function currently called "result", is
displayed.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
User-Defined Functions
599
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.
5.
Click the Insert input component icon
to insert an input component.
Enter the name of the input parameter, ArticleNr in this case, and click OK.
6.
This component acts as a data input to the user-defined function and supplies the input
icon of the user-defined function.
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
© 2017 Altova Gmb H
in the toolbar.
Altova MapForce 2017 Professional Edition
600
Functions
User-Defined Functions
Use the diagram below as an aid to creating the mappings in the user-defined function,
please take note of the following:
8
9.
Right click the a parameter and select Priority context from the pop up menu.
Double click the output function and enter the name of the output parameter, in this
case "Name".
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.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
User-Defined Functions
601
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.
10. Create the connections displayed in the graphic below and click the Output tab to see the
result of the mapping.
8.2.4
User-defined function - example
The PersonListByBranchOffice.mfd file available in the <Documents>\Altova\MapForce2017
\MapForceExamples\ folder illustrates the following features:
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
602
Functions
User-Defined Functions
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!
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.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
User-Defined Functions
603
To define the Input value:
1.
2.
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.
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 Components for more information.
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
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
604
Functions
User-Defined Functions
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.
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.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
User-Defined Functions
605
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.
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).
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
606
8.2.5
Functions
User-Defined Functions
Complex user-defined function - XML node as input
This example is provided as the lookup-udf-in.mfd file available in the ...\MapForceExamples
folder. This section illustrates 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.
The left half contains the input parameters:
a simple input parameter POArtNr
a complex input component Articles, with mappings directly to its XML child nodes
The right half contains a simple output parameter called "Name".
The screenshot below shows the constituent components of the user-defined function, the two
input components to the left and the output component to the right.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
8.2.5.1
User-Defined Functions
607
Defining Complex Input Components
Follow these steps to create a function that takes an XML structure as input parameter:
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.
3.
Click the Insert input component icon
in the icon bar.
Enter the name of the input component into the Name field.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
608
Functions
4.
User-Defined Functions
Click the Complex type (tree structure) radio button, then click the "Choose" button
next to the Structure field. This opens another dialog box.
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, database file.
The lower list box allows you to select a new complex data structure i.e. XML Schema,
Database file, file.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
User-Defined Functions
5.
6.
7.
609
Click "Insert a new structure... " radio button, select the XML Schema Structure entry,
and click OK to continue.
Select Articles.xsd from the "Open" dialog box.
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
icon
to the left of the component name. This shows that the component is used as a
complex input component.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
610
Functions
8.
User-Defined Functions
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.
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 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.
12. Create the connections as shown in the screenshot below.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
User-Defined Functions
611
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 the filtered line
items which have the same Article number to the "Name" item of CompletePO.
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.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
612
8.2.6
Functions
User-Defined Functions
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.
8.2.6.1
Defining Complex Output Components
Follow these steps to create a function that returns an XML structure as output parameter:
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.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
User-Defined Functions
2.
Click the Insert Output icon
3.
Click the Complex type... radio button, then click the "Choose" button.
This opens another dialog box.
613
in the icon bar, and enter a name e.g. CompletePO.
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 , database file.
The lower list box allows you to select a new complex data structure i.e. XML Schema,
Database file, file.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
614
Functions
4.
5.
6.
User-Defined Functions
Click "Insert new structure... " radio button, select the XML Schema Structure entry,
and click OK to continue.
Select the CompletePO.xsd from the "Open" dialog box.
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
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
User-Defined Functions
615
output icon
to the left of the component name. This shows that the component is used
as a complex output component.
7.
8.
Insert the Articles schema/XML file into the user-defined function and assign the
Articles.xml as the XML instance.
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.
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 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.
11. Create the connections as shown in the screenshot below.
Having created the Article (CompletePO) connector to the target, right click it and select
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
616
Functions
User-Defined Functions
"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.
8.2.7
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
MapForceExamples project folder contains further examples of recursive mappings.
The screenshot below shows the finished mapping containing the recursive user-defined function
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
User-Defined Functions
617
FilterDirectory, the aim being to filter 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.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
618
8.2.7.1
Functions
User-Defined Functions
Defining a recursive user-defined function
Follow these steps to create a recursive user-defined function:
1.
2.
3.
4.
Select Function | Create User defined Function to start designing the function and
enter a name e.g. FilterDirectory.
Make sure that you deselect the Inlined Use check box in the Implementation group, to
make the function recursive, then click OK.
You are now in the FilterDirectory window where you create the user-defined function.
Select Function | Insert Input to insert an input component.
Give the component a name e.g. "directory" and click on the Complex Type (tree
structure) radio button.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
User-Defined Functions
5.
Click the Choose button, click the "XML Schema Structure" entry in the lower pane, then
click OK.
6.
Select the Directory.xsd file in the ...\MapForceExamples folder and click the Open
button.
Click OK again when asked to select the root item, which should be "directory" as shown
below.
7.
© 2017 Altova Gmb H
619
Altova MapForce 2017 Professional Edition
620
Functions
8.
User-Defined Functions
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 Function | Insert Input... and insert a component of type Simple type, and enter
a name e.g. SearchFor. Deselect the "Input is required" check box.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
User-Defined Functions
621
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 userdefined function window. (You could do this at almost any point however.)
1.
2.
Find the FilterDirectory function in the user section of the Libraries window.
Click FilterDirectory then drag and drop it into the FilterDirectory window you have just
been working in.
The user-defined function now appears in the user-defined function window as a recursive
component.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
622
Functions
3.
4.
5.
6.
7.
User-Defined Functions
Connect the directory, name and file items of the input component to the same items
in the output component.
Right click the connector between the file items and select "Insert Filter" to insert a filter
component.
Right click the on-true connector and select Copy-All from the context menu.
The connectors change appearance to Copy-All connectors.
Insert a Contains function from the Core | String functions library.
Connect name to value and the SearchFor parameter to substring, then result to the
bool item of the filter.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
User-Defined Functions
8.
623
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.
1.
2.
3.
Making sure that the Toggle Autoconnect icon
is active in the icon bar:
Connect the lower directory item of the input component to the top directory item of the
recursive user-defined function.
Connect the top output directory item of the user-defined function to the lower directory
item of the output component.
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.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
624
Functions
User-Defined Functions
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.
2.
3.
4.
5.
6.
7.
Drag the FilterDirectory function from the user section of the Libraries window, into the
main mapping area.
Use Insert | XML Schema file to insert Directory.xsd and select Directory.xml as the
instance file.
Use the same method to insert Directory.xsd and select Skip, to create the output
component.
Insert a constant component, then a Input component e.g. SearchFor.
Create the connections as shown in the screenshot below.
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.
Click the Output tab to see the result of the mapping.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
User-Defined Functions
625
Notes:
Double 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.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
626
8.3
Functions
Importing Custom XSLT 1.0 or 2.0 Functions
Importing Custom XSLT 1.0 or 2.0 Functions
You can extend the XSLT 1.0 and 2.0 function libraries available in MapForce with your own
custom functions, provided that your custom functions return simple types.
Only custom functions that return simple data types (for example, strings) are supported.
To import functions from an XSLT file:
1.
2.
On the Tools menu, click Options. (Alternatively, click Add/Remove Libraries in the
lower area of the Libraries window.)
Next to Libraries, click Add and browse for the .xsl or .xslt file.
Imported XSLT files appear as libraries in the Libraries window, and display all named templates
as functions below the library name. If you do not see the imported library, ensure you selected
XSLT as transformation language (see Selecting a Transformation Language).
Note the following:
To be eligible for import into MapForce, functions must be declared as named templates
conforming to the XSLT specification in the XSLT file. You can also import functions that
occur in an XSLT 2.0 document in the form <xsl:function name="MyFunction">. If the
imported XSLT file imports or includes other XSLT files, then these XSLT files and
functions will be imported as well.
The mappable input connectors of imported custom functions depends on the number of
parameters used in the template call; optional parameters are also supported.
Namespaces are supported.
If you make updates to XSLT files that you have already imported into MapForce,
changes are detected automatically and MapForce prompts you to reload the files.
When writing named templates, make sure that the XPath statements used in the
template are bound to the correct namespace(s). To see the namespace bindings of the
mapping, preview the generated XSLT code.
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.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Importing Custom XSLT 1.0 or 2.0 Functions
627
Value comparison operators promote operands to xs:string before comparing.
See also:
Example: Adding Custom XSLT 1.0 Functions
Example: Summing Node Values
XSLT 1.0 engine implementation
XSLT 2.0 engine implementation
8.3.1
Example: Adding Custom XSLT Functions
This example illustrates how to import custom XSLT 1.0 functions into MapForce. The files
needed for this example are available in the <Documents>\Altova\MapForce2017
\MapForceExamples\ directory.
Name-splitter.xslt. This XSLT file defines a named template called "tokenize" with a
single parameter "string". The template works through an input string and separates
capitalized characters with a space for each occurrence.
Name-splitter.xml (the source XML instance file to be processed)
Customers.xsd (the source XML schema)
CompletePO.xsd (the target XML schema)
To add a custom XSLT function:
1.
2.
3.
Select XSLT as transformation language (see Selecting a Transformation Language).
Click the Add/Remove Libraries button, in the lower area of the Libraries window.
Alternatively, on the Tools menu, click Options, and then select Libraries.
Click Add, and browse for the XSL, or XSLT file, that contains the named template you
want to act as a function, in this case Name-splitter.xslt.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
628
Functions
4.
Importing Custom XSLT 1.0 or 2.0 Functions
Click OK. The XSLT file name appears in the Libraries window, along with the functions
defined as named templates (in this example, Name-splitter with the tokenize function).
To use the XSLT function in your mapping:
1.
Drag the tokenize function into the Mapping window and map the items as show below.
2.
Click the XSLT tab to see the generated XSLT code.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Importing Custom XSLT 1.0 or 2.0 Functions
Note:
3.
629
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.
Click the Output tab to see the result of the mapping.
To remove custom XSLT libraries from MapForce:
1.
2.
Click the Add/Remove Libraries button, in the lower area of the Libraries window.
Click the XSLT library to be deleted, and then click Delete.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
630
8.3.2
Functions
Importing Custom XSLT 1.0 or 2.0 Functions
Example: Summing Node Values
This example shows you how to process multiple nodes of an XML document and have the result
mapped as a single value to a target XML document. Specifically, the goal of the mapping is to
calculate the price of all products in a source XML file and write it as a single value to an output
XML file. The files used in this example are available in the <Documents>\Altova\MapForce2017
\MapForceExamples\Tutorial\ folder:
Summing-nodes.mfd — the mapping file
input.xml — the source XML file
input.xsd — the source XML schema
output.xsd — the target XML schema
Summing-nodes.xslt — A custom XSLT stylesheet containing a named template to
sum the individual nodes.
There are two different ways to achieve the goal of the mapping:
By using the sum aggregate function of the core library. This function is available in the
Libraries window (see also Working with Functions).
By importing a custom XSLT stylesheet into MapForce.
Solution 1: Using the "sum" aggregate function
To use the sum aggregate function in the mapping, drag it from the Libraries window into the
mapping. Note that the functions available in the Libraries window depend on the XSLT language
version you selected (XSLT 1 or XSLT 2). Next, create the mapping connections as shown below.
For more information about aggregate functions of the core library, see also core | aggregate
functions.
Solution 2: Using a custom XSLT Stylesheet
As mentioned above, the aim of the example is to sum the Price fields of products in the source
XML file, in this case products A and B.
<?xml version="1.0" encoding="UTF-8"?>
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Importing Custom XSLT 1.0 or 2.0 Functions
631
<Input xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="input.xsd">
<Products>
<Product>
<Name>ProductA</Name>
<Amount>10</Amount>
<Price>5</Price>
</Product>
<Product>
<Name>ProductB</Name>
<Amount>5</Amount>
<Price>20</Price>
</Product>
</Products>
</Input>
The image below shows a custom XSLT stylesheet which uses the named template "Total" and a
single parameter string. The template works through the XML input file and sums all the values
obtained by the XPath expression /Product/Price.
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/
Transform">
<xsl:output method="xml" version="1.0" encoding="UTF-8" indent="yes"/>
<xsl:template match="*">
<xsl:for-each select=".">
<xsl:call-template name="Total">
<xsl:with-param name="string" select="."/>
</xsl:call-template>
</xsl:for-each>
</xsl:template>
<xsl:template name="Total">
<xsl:param name="string"/>
<xsl:value-of select="sum($string/Product/Price)"/>
</xsl:template>
</xsl:stylesheet>
Note:
To sum the nodes in XSLT 2.0, change the stylesheet declaration to version="2.0".
To import the XSLT stylesheet into MapForce:
1.
2.
3.
4.
5.
Select XSLT as transformation language. For more information, see Selecting a
Transformation Language.
In the Libraries window, click Add/Remove Libraries.
On the Options dialog box, click the Libraries tab.
Click Add and browse for <Documents>\Altova\MapForce2017\MapForceExamples
\Tutorial\Summing-nodes.xslt.
Drag the Total function from the newly created "Summing-nodes" library into the mapping,
and create the mapping connections as shown below.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
632
Functions
Importing Custom XSLT 1.0 or 2.0 Functions
To preview the mapping result, click the Output tab. The sum of the two Price fields is now
displayed in the Total field.
<?xml version="1.0" encoding="UTF-8"?>
<Output xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="output.xsd">
<Total>25</Total>
<Product>
<Name>ProductA</Name>
<Amount>10</Amount>
<Price>5</Price>
</Product>
<Product>
<Name>ProductB</Name>
<Amount>5</Amount>
<Price>20</Price>
</Product>
</Output>
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
8.4
Importing Custom XQuery 1.0 Functions
633
Importing Custom XQuery 1.0 Functions
When XQuery is selected as mapping transformation language, MapForce displays the function
libraries available for XQuery in the Libraries window. If necessary, you can extend this list with
custom XQuery functions, by importing custom XQuery 1.0 library modules into MapForce.
To be eligible for import into MapForce, an XQuery file must satisfy the following requirements:
It must be a valid library module according to XQuery specification. In other words, it must
start with a module declaration such as module namespace <prefix>="<namespace
name"
All functions declared in the imported library module must return atomic data types (for
example, xs:string, xs:boolean, xs:integer, etc). Function parameters must also
have atomic types.
To import an XQuery library module:
1.
2.
On the Tools menu, click Options. (Alternatively, click Add/Remove Libraries in the
lower area of the Libraries window.)
Next to Libraries, click Add and browse for the .xq or .xquery library file.
If the imported library module is not supported, a message box prompts you. Otherwise, the
imported library modules appear in the Libraries window, and then you can drag specific functions
into the mapping area and use them like any other MapForce function component.
If you do not see the imported XQuery library module, make sure that XQuery is selected as
transformation language (see Selecting a Transformation Language).
See also:
XQuery engine implementation
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
634
8.5
Functions
Importing Custom Java and .NET Libraries
Importing Custom Java and .NET Libraries
Compiled Java class files as well as .NET DLL assemblies (including .NET 4.0 assemblies) can
be imported into MapForce. If the imported libraries contain functions that use basic data types as
parameters and return simple types, such functions appear in the Libraries window, and can be
used in mappings as any other function available in MapForce. The mapping output of imported
Java and .NET functions can be previewed in the Output pane and the functions are available in
generated code.
Notes:
To import custom Java or .NET functions, you need compiled Java classes (.class) or the
.NET.dll assembly files. Importing Java .jar files or .dll files that are not a .NET assembly
is not supported.
Compiled Java class (.class) files are supported when the mapping language is set to
Java. Java Runtime Environment 7 or later must be installed on your computer. Only
specific types and members are supported (see Java function support).
.NET assembly files are supported when the mapping language is set to C#. The .NET
assemblies may be written in .NET languages other than C# (for example, C++.NET or
VB.NET), provided they use only the basic data types from the System Assembly as
parameters and return types (see also .NET Function Support).
Setting the mapping language to C++ is not supported if the mapping uses imported Java
.class or .NET DLL assemblies.
Importing functions from native C++ DLLs is limited and requires a special approach. For
more information, see Referencing Java, C# and C++ Libraries Manually.
Setting the mapping language to XSLT is not supported if the mapping uses imported
Java .class or .NET DLL assemblies (a custom XSLT function that acts as an adapter
would have to be written).
All functions called from a MapForce mapping should be “idempotent” (this means that
they should return the same value each time the function is called with the same input
parameters). The exact order and the number of times a function is called by MapForce is
undefined.
In case of Java, the imported class files and their packages do not need to be added to
the CLASSPATH variable, since the Built-in execution engine, as well as generated Java
code, will automatically add imported packages to the Java engine’s classpath or to Ant,
respectively. However, any dependencies of the imported class files and packages will
not be handled automatically. Therefore, if imported Java class files or packages depend
on other class files, be sure to add the parent directories of all dependent packages to
the CLASSPATH environment variable.
Java function support
Top-level classes, static member classes and non-static member classes are supported:
new <classname>(<arg1>, <arg2>, ...)
<object>.new <member-class>(<arg1>, <arg2>, ...)
Member functions and static functions are supported:
<function>(<arg1>, <arg2>, ...)
<object>.<method>(<arg1>, ...)
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Importing Custom Java and .NET Libraries
635
Supported connections between XML Schema and Java types:
Schema type
Java type
xs:string
String
xs:byte
byte
xs:short
short
xs:int
int
xs:long
long
xs:boolean
boolean
xs:float
float
xs:double
double
xs:decimal
java.math.BigDecimal
xs:integer
java.math.BigInteger
Connections in both directions are possible. Other Java types (including array types) are not
supported. Methods using such parameters or return values, will be ignored.
Object types are supported by calling their constructor, or as a return value of a method. They can
be mapped to other Java methods. Manipulating the object using MapForce means is not
possible.
.NET function support
Top-level classes and member classes are supported:
new <classname>(<arg1>, <arg2>, ...)
Member functions and static functions are supported:
<function>(<arg1>, <arg2>, ...)
<object>.<method>(<arg1>, ...)
Supported connections between XML Schema and .NET/C# types:
Schema type
.NET type
C# type
xs:string
System.String
string
xs:byte
System.SByte
sbyte
xs:short
System.Int16
short
xs:int
System.Int32
int
xs:long
System.Int64
long
xs:unsignedByte
System.Byte
byte
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
636
Functions
Schema type
Importing Custom Java and .NET Libraries
.NET type
C# type
xs:unsignedShort
System.UInt16
ushort
xs:unsignedInt
System.UInt32
uint
xs:unsignedLong
System.UInt64
ulong
xs:boolean
System.Boolean
bool
xs:float
System.Single
float
xs:double
System.Double
double
xs:decimal
System.Decimal
decimal
Connections in both directions are possible. Other .NET/C# types (including array types) are not
supported. Methods using such parameters or return values will be ignored.
Object types are supported by calling their constructor, or as a return value of a method. They can
be mapped to other .NET methods. Manipulating the object using MapForce means is not
possible.
8.5.1
Example: Import Custom Java Class
This example illustrates how to import a custom Java .class file into MapForce.
Note:
Java SE 7 Runtime Environment or later is required to complete this example.
To add the Java .class file as MapForce library:
1.
2.
3.
Set the transformation language to Java (see Selecting a Transformation Language).
Click the Add/Remove Libraries button in the lower area of the Libraries window.
Next to Libraries, click Add, and select the Format.class file from the ...
\MapForceExamples\Java\Format\ directory. A message appears telling you that a
new library has been added. The imported library is now visible in the Libraries window.
To preview the mapping output in MapForce:
1.
2.
Open the FormatNumber.mfd file available in the ...\MapForceExamples\Java folder.
Click the Output button to see the result of the mapping.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Importing Custom Java and .NET Libraries
637
To run the mapping in Java:
1.
2.
3.
8.5.2
On the File menu, click Generate Code In | Java.
Select a target directory where the code should be generated, and click OK.
Import the generated libraries into your Java project and build the Java application (for an
example, see Example: Build a Java application with Eclipse and Ant ).
Example: Import Custom .NET DLL Assembly
This example illustrates how to import into MapForce a custom .NET DLL assembly created in
C#.
To add the .NET assembly file:
1.
2.
3.
Set the transformation language to C# (see Selecting a Transformation Language).
Click the Add/Remove Libraries button in the lower area of the Libraries window.
Next to Libraries, click Add, and select the Format.dll file from the ...
\MapForceExamples\C#\Format\bin\Debug\ directory. A message appears telling you
that a new library has been added. The imported library is now visible in the Libraries
window.
To preview the mapping output:
1.
2.
Open the FormatNumber.mfd file available in the ...\MapForceExamples\C# folder.
Click the Output button to see the result of the mapping.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
638
Functions
Importing Custom Java and .NET Libraries
To run the mapping from a custom C# application:
1.
2.
3.
On the File menu, click Generate Code In | C#.
Select a target directory where the code should be generated, and click OK.
Build the application with Visual Studio, and run the generated console application (see
also Generating C# code).
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
8.6
Referencing Java, C# and C++ Libraries Manually
639
Referencing Java, C# and C++ Libraries Manually
As an alternative approach to importing custom libraries into MapForce directly, you can create
references to them using a custom .mff file (MapForce Function File) recognized by MapForce.
The .mff library file is essentially an XML file where you manually define the linking between class
definitions in your custom code and MapForce. Once you create the custom .mff file, you can
import it into MapForce, similar to how you would import a .NET DLL or Java class file.
Notes:
For an imported function to appear in the Libraries window, its return type and parameters
must be of a simple type. For a list of data types available for each language, see Data
Type Mapping.
When you import function libraries from custom .mff files, the preview of the mapping
directly in MapForce (by clicking the Output button) is limited. For libraries written in C+
+, preview of the mapping in MapForce is not supported. In case of Java and C#, preview
is available when your library uses native language types, but it is not available if your
library imports the Altova generated classes. Note, however, that you can generate code
in the specific language targeted by your library. The custom functions will be available in
the generated code, enabling you to run the mapping from the generated code.
The exact order in which functions are called by the generated mapping code is
undefined. MapForce may cache calculated results for reuse, or evaluate expressions in
any order. It is therefore strongly recommended to use only custom functions that have
no side effects.
It is important to distinguish between user-defined functions and custom function libraries.
User-defined functions are created graphically in a mapping, and they cannot and need
not be saved to an *.mff file, because they are saved together with the mapping .mfd file
where they have been created. For more information, see Reusing (importing) UserDefined Functions.
If you are upgrading from a MapForce version earlier than 2010, you may need to update
the data types used in your custom functions (see Data Type Mapping).
For instructions on how to create and configure a custom .mff file, see Configuring the .mff File.
For examples, see:
Example: Create a Custom C# Library
Example: Create a Custom C++ Library
Example: Create a Custom Java Library
8.6.1
Configuring the .mff File
The MapForce Function File (.mff) is a configuration file in XML format that makes it possible to
adapt functions from custom Java, C#, or C++ libraries into MapForce, so that they appear in the
Libraries window. An .mff file essentially intermediates between your custom libraries and
MapForce, and it must be configured to specify a) the interfaces to the custom functions and b)
where the implementation can be found in generated code. This topic provides instructions on how
to do this.
Note:
The *.mff library files must be valid against the mff.xsd schema file found in the Altova
\MapForce2017\MapForceExamples folder, relative to your (My) Documents folder.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
640
Functions
Referencing Java, C# and C++ Libraries Manually
The mff.xsd schema defines the custom library configuration and is for internal use only.
Altova GmbH retains the right to change this file format with new releases.
The following code listing illustrates a sample .mff file for C#:
<?xml version="1.0" encoding="UTF-8"?>
<mapping xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xsi:noNamespaceSchemaLocation="mff.xsd" version="8" library="helloworld">
<implementations>
<implementation language="cs">
<setting name="namespace" value="HelloWorldLibrary"/>
<setting name="class" value="Greetings"/>
<setting name="reference" value="C:\HelloWorldLibrary
\HelloWorldLibrary.dll"/>
</implementation>
</implementations>
<group name="string functions">
<component name="hello">
<sources>
<datapoint name="greeting_type" type="xs:boolean"/>
</sources>
<targets>
<datapoint name="result" type="xs:string"/>
</targets>
<implementations>
<implementation language="cs">
<function name="HelloFunction"/>
</implementation>
</implementations>
<description>
<short>result = hello(greeting_type)</short>
<long>Returns a greeting sentence according to the given
greeting_type.</long>
</description>
</component>
</group>
</mapping>
The image below shows a custom .mff file may look after import into MapForce. Notice that the
custom library "helloworld" appears as a library entry (sorted alphabetically), containing the "hello"
string function.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Referencing Java, C# and C++ Libraries Manually
641
The steps needed to adapt the mff file to suit your needs are described below.
Configuring the library name
The library name is found in the .mff file line shown below. By convention, the library name is
written in lowercase letters.
<mapping xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xsi:noNamespaceSchemaLocation="mff.xsd" version="8" library="helloworld">
In the sample above, the entry that will appear in the Libraries window will be called "helloworld".
Configuring the language implementations
The <implementations> element is mandatory element which specifies which languages your
library should support, and it must be added as child of <mapping>, for example:
...
<mapping xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xsi:noNamespaceSchemaLocation="mff.xsd" version="8" library="helloworld">
<implementations>
<implementation language="cs">
<setting name="namespace" value="HelloWorldLibrary"/>
<setting name="class" value="Greetings"/>
<setting name="reference" value="C:\HelloWorldLibrary
\HelloWorldLibrary.dll"/>
</implementation>
</implementations>
...
The settings within each <implementation> allow the generated code to call the specific
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
642
Functions
Referencing Java, C# and C++ Libraries Manually
functions defined in Java, C++ or C#.
An .mff file can be written so that it targets more than one programming language. In this case,
every additional language must contain an additional <implementation> element. The specific
settings for each programming language are discussed below.
Java
...
<implementation language="java">
<setting name="package" value="com.hello.functions"/>
<setting name="class" value="Hello"/>
</implementation>
...
It is important for the generated code to be able to find your Hello.class file. Therefore, make sure
that your class is in the Java classpath. The default Java classpath is found in the system
environment variables.
Note that it is only possible to have one class per *.mff file when working with custom Java
libraries.
C#
...
<implementation language="cs">
<setting name="namespace" value="HelloWorldLibrary"/>
<setting name="class" value="Hello"/>
<setting name="reference" value=" C:\HelloWorldLibrary
\HelloWorldLibrary.dll"/>
</implementation>
...
For C#, it is important that the namespace in the code corresponds to the namespace defined in
the .mff file (in the code listing above, the namespace is HelloWorldLIbrary). The same is true
for the class name (in the code listing above, the class name is Hello). The third setting,
reference, provides the path of the dll that is to be linked to the generated code.
C++
...
<implementation language="cpp">
<setting name="namespace" value="helloworld"/>
<setting name="class" value="Greetings"/>
<setting name="path" value="C:\HelloWorldLibrary"/>
<setting name="include" value="Greetings.h"/>
<setting name="source" value="Greetings.cpp"/>
</implementation>
...
For the C++ sample listing above, note the following:
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Referencing Java, C# and C++ Libraries Manually
643
namespace is the namespace in which your Greetings class will be defined. It must be
equal to the library name.
path is the path in which the include and the source files are to be found.
When code for a mapping is generated, the include and source files will be copied to the
directory targetdir/libraryname (defined when selecting the menu option File |
Generate xxx code, and selecting the directory) and included in the project file.
All the include files you supply will be included in the generated algorithm.
Adding a component
In the Libraries window of the MapForce graphics user interface, each function appears nested
under a function group, for example "string functions". In the .mff file, a function corresponds to a
<component> element. Conversely, each <component> must be nested under a <group> element,
for example:
...
<group name="string functions">
<component name="hello">
…
</component>
</group>
...
The code shown below defines a sample function (component) called hello.
...
<component name="hello">
<sources>
<datapoint name="greeting_type" type="xs:boolean"/>
</sources>
<targets>
<datapoint name="result" type="xs:string"/>
</targets>
<implementations>
…
</implementations>
<description>
<short>result = hello(greeting_type)</short>
<long>Returns a greeting sentence according to the given
greeting_type.</long>
</description>
</component>
...
Here is how the component above would look in MapForce:
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
644
Functions
Referencing Java, C# and C++ Libraries Manually
In the code listing above, a <datapoint> can be loosely defined as the input or output parameter
of a function (also known as input or output connector). The type argument of the <datapoint>
specifies the data type of the parameter (or the data type of the return value).
Only one target datapoint is allowed for each function. There is no limitation as to how many
source datapoints you can define.
The data type of each datapoint must be one of the XML Schema types (for example, xs:string,
xs:integer, etc.) These data types have to correspond to the data types of the function's
parameters you defined in your Java, C++ or C# library. For the mapping of XML Schema
datatypes to language types, see Data Type Mapping.
Functions are accompanied by short and long descriptions in the library window. The short
description is always shown to the right of the function name, while the long description is
displayed as a ToolTip when you place the mouse cursor over the short description.
Short description:
Long description:
Defining language implementations
We are now at the point where we need to make a connection between the function in the
Libraries window, and the function in the custom Java, C# or C++ classes. This is achieved
through the <implementation> element.
As previously stated, one function may have multiple implementation elements – one for each
supported programming language. A function may be called "helloFunction" in Java, or
"HelloFunctionResponse" in C++. This is why you need to specify a separate function name for
each programming language. A function for each of the three programming languages might look
like the following:
...
<component name="hello">
...
<implementations>
<implementation language="cs">
<function name="HelloFunction"/>
</implementation>
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Referencing Java, C# and C++ Libraries Manually
645
<implementation language="java">
<function name="helloFunction"/>
</implementation>
<implementation language="cpp">
<function name="HelloFunctionResponse"/>
</implementation>
</implementations>
...
</component>
...
The value you supply as function name must exactly match the name of the method in the Java,
C# or C++ class.
8.6.2
Importing the .mff File Into MapForce
After you have created a custom .mff file (see Configuring the .mff File ), you can import it into
MapForce as follows:
1.
2.
On the Tools menu, click Options. (Alternatively, click Add/Remove Libraries in the
lower area of the Libraries window.)
Next to Libraries, click Add, and select the custom .mff file.
The imported library becomes visible in the Libraries window after you set the mapping language
to a language targeted by the custom library.
If you save the *.mff file in the ...\Altova\MapForce2017\MapForceLibraries folder relative to the
Program Files (or Program Files (x86) folder), then the library is automatically loaded into
Libraries window when you start MapForce. Libraries and their functions can be toggled on or off,
by deleting or adding the respective library file (*.mff).
8.6.3
Data Type Mapping
The following table lists the data types supported as function return types and parameter types
when you create custom .mff files that adapt your Java, C#, and C++ libraries to MapForce. The
table lists both native and non-native data types. Note that, if you need support for non-native data
types such as Altova date, time and duration types, your custom Java and C# libraries must
include a reference to Altova libraries. In case of C++, Altova libraries must always be imported.
For information about how to generate the Altova libraries, see Code Generator.
XML Schema
Type
Java Type
C# Type
C++ Type
anyAtomicType
String
string
string_type
anySimpleType
String
string
string_type
anyURI
String
string
string_type
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
646
Functions
Referencing Java, C# and C++ Libraries Manually
XML Schema
Type
Java Type
C# Type
C++ Type
base64Binary
byte[]
byte[]
altova::mapforce::
blob
boolean
boolean
bool
bool
byte
int
int
int
date
com.altova.types.D
ateTime
Altova.Types.DateT
ime
altova::DateTime
dateTime
com.altova.types.D
ateTime
Altova.Types.DateT
ime
altova::DateTime
dayTimeDuration
com.altova.types.D
uration
Altova.Types.Durat
ion
altova::Duration
decimal
java.math.BigDecim
al
decimal
double
double
double
double
double
duration
com.altova.types.D
uration
Altova.Types.Durat
ion
altova::Duration
ENTITIES
String
string
string_type
ENTITY
String
string
string_type
float
double
double
double
gDay
com.altova.types.D
ateTime
Altova.Types.DateT
ime
altova::DateTime
gMonth
com.altova.types.D
ateTime
Altova.Types.DateT
ime
altova::DateTime
gMonthDay
com.altova.types.D
ateTime
Altova.Types.DateT
ime
altova::DateTime
gYear
com.altova.types.D
ateTime
Altova.Types.DateT
ime
altova::DateTime
gYearMonth
com.altova.types.D
ateTime
Altova.Types.DateT
ime
altova::DateTime
hexBinary
byte[]
byte[]
altova::mapforce::
blob
ID
String
string
string_type
IDREF
String
string
string_type
IDREFS
String
string
string_type
int
int
int
int
integer
java.math.BigInteg
er
decimal
__int64
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Referencing Java, C# and C++ Libraries Manually
XML Schema
Type
Java Type
C# Type
C++ Type
language
String
string
string_type
long
long
long
__int64
Name
String
string
string_type
NCName
String
string
string_type
negativeInteger
java.math.BigInteg
er
decimal
__int64
NMTOKEN
String
string
string_type
NMTOKENS
String
string
string_type
nonNegativeInteg
er
java.math.BigInteg
er
decimal
unsigned __int64
nonPositiveInteg
er
java.math.BigInteg
er
decimal
__int64
normalizedString
String
string
string_type
NOTATION
String
string
string_type
positiveInteger
java.math.BigInteg
er
decimal
unsigned __int64
QName
javax.xml.namespac
e.QName
Altova.Types.QName
altova::QName
short
int
int
int
string
String
string
string_type
time
com.altova.types.D
ateTime
Altova.Types.DateT
ime
altova::DateTime
token
String
string
string_type
unsignedByte
long
ulong
unsigned __int64
unsignedInt
long
ulong
unsigned __int64
unsignedLong
java.math.BigInteg
er
ulong
unsigned __int64
unsignedShort
long
ulong
unsigned __int64
untypedAtomic
String
string
string_type
yearMonthDuratio
n
com.altova.types.D
uration
Altova.Types.Durat
ion
altova::Duration
© 2017 Altova Gmb H
647
Altova MapForce 2017 Professional Edition
648
8.6.4
Functions
Referencing Java, C# and C++ Libraries Manually
Example: Create a Custom C# Library
This topic describes how to create a sample C# library and configure the .mff file so that it
appears in the Libraries window of MapForce.
1.
Create a new class library project in Visual Studio. Notice that the function has been
defined as public static.
using System;
namespace HelloWorldLibrary
{
public class Greetings
{
public static string HelloFunction(bool GreetingType)
{
if (GreetingType)
return "Hello World!";
return "Hello User!";
}
}
}
2.
3.
4.
If you need special XML Schema types (such as date and duration), you will need add a
reference from your Visual Studio project to the Altova.dll library. To obtain this library,
generate C# code from a mapping without custom functions. The Altova.dll file will be
located in the ..\Altova\bin\debug directory relative to the directory where the code was
generated. To add the reference to Altova.dll in Visual Studio, on the Project menu,
click Add Reference and browse for the Altova.dll file. Also, add to your code the
following line: using Altova.Types; . For information about how XML Schema types
map to C# types, see Data Type Mapping.
Build your Visual Studio project. The HelloWorldLibrary.dll is generated in your project
output directory.
Using an XML editor, create a new .mff file and validate it against the ..\Program Files
\MapForceLibraries\mff.xsd folder. Make sure that the text highlighted below points to
the HelloWorldLibrary.dll file. For more information, see Configuring the .mff File.
<?xml version="1.0" encoding="UTF-8"?>
<mapping version="9" library="helloworld" xmlns:xs="http://
www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance" xsi:noNamespaceSchemaLocation="mff.xsd">
<implementations>
<implementation language="cs">
<setting name="namespace" value="HelloWorldLibrary"/>
<setting name="class" value="Greetings"/>
<setting name="reference" value="C:\Projects
\HelloWorldLibrary.dll"/>
</implementation>
</implementations>
<group name="Greetings">
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Referencing Java, C# and C++ Libraries Manually
649
<component name="HelloFunction">
<sources>
<datapoint name="greeting_type" type="xs:boolean"/>
</sources>
<targets>
<datapoint name="result" type="xs:string" />
</targets>
<implementations>
<implementation language="cs">
<function name="HelloFunction"/>
</implementation>
</implementations>
<description>
<short>result = hello(greeting_type)</short>
<long>Returns a greeting according to the given greeting
type.</long>
</description>
</component>
</group>
</mapping>
You have now finished creating a custom library and the .mff file which adapts it to MapForce. The
custom .mff file can now be used in MapForce (see Importing the .mff File Into MapForce).
8.6.5
Example: Create a Custom C++ Library
This topic describes how to create a sample C++ library and configure a .mff file for it so that the
library appears in the Libraries window of MapForce.
1.
Create a header (.h) file for your class library. The following code listing illustrates a
sample header file called Greetings.h.
#ifndef HELLOWORLDLIBRARY_GREETINGS_H_INCLUDED
#define HELLOWORLDLIBRARY_GREETINGS_H_INCLUDED
#if _MSC_VER > 1000
#pragma once
#endif // _MSC_VER > 1000
using namespace altova;
namespace helloworld {
class ALTOVA_DECLSPECIFIER Greetings
{
public:
static string_type
HelloFunctionResponse(bool greetingType);
};
} // namespace HelloWorldLibrary
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
650
Functions
Referencing Java, C# and C++ Libraries Manually
#endif // HELLOWORLDLIBRARY_GREETINGS_H_INCLUDED
Notice that the function has been declared as static, and that the namespace altova is
imported. Remember to write ALTOVA_DECLSPECIFIER in front of the class name, this
ensures that your classes will compile correctly—whether you use dynamic or static
linkage in subsequently generated code.
2.
Create a .cpp file with the same name as the header file. The .cpp file must be in the
same directory as the .h file. The following code listing illustrates a sample .cpp file
called Greetings.cpp that includes the Greetings.h file created previously:
#include
#include
#include
#include
"StdAfx.h"
"../Altova/Altova.h"
"../Altova/AltovaException.h"
"../Altova/SchemaTypes.h"
#include "Greetings.h"
namespace helloworld {
string_type
Greetings::HelloFunctionResponse(bool greetingType)
{
if( greetingType )
return _T("Hello World!");
return _T("Hello User!");
}
}
Notice the lines that import the StdAfx.h and several Altova libraries. These lines must
be left unchanged. The paths to the Altova libraries is correct; in the generated code,
these paths will point to the respective files.
In contrast to Java or C#, you do not need to compile your source C++ files. They will
be copied to the generated code, and are compiled with the rest of the generated
mapping code.
3.
Using an XML editor, create a new .mff file and validate it against the ..\Program Files
\MapForceLibraries\mff.xsd folder. Make sure that the text highlighted below points to
the directory of the header and cpp files created previously. Remember that the
namespace and function names and data types defined here must correspond to those in
the C++ code, as described in Configuring the .mff File. For information about data type
support, see Data Type Mapping.
<?xml version="1.0" encoding="UTF-8"?>
<mapping version="9" library="helloworld" xmlns:xs="http://
www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance" xsi:noNamespaceSchemaLocation="mff.xsd">
<implementations>
<implementation language="cpp">
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Referencing Java, C# and C++ Libraries Manually
651
<setting name="namespace" value="helloworld"/>
<setting name="class" value="Greetings"/>
<setting name="path" value="C:\Projects\HelloWorld"/>
<setting name="include" value="Greetings.h"/>
<setting name="source" value="Greetings.cpp"/>
</implementation>
</implementations>
<group name="Greetings">
<component name="HelloFunctionResponse">
<sources>
<datapoint name="greeting_type" type="xs:boolean"/>
</sources>
<targets>
<datapoint name="result" type="xs:string"/>
</targets>
<implementations>
<implementation language="cpp">
<function name="HelloFunctionResponse"/>
</implementation>
</implementations>
<description>
<short>result = hello(greeting_type)</short>
<long>Returns a greeting according to the given greeting
type.</long>
</description>
</component>
</group>
</mapping>
You have now finished creating a custom library and the .mff file which adapts it to MapForce. The
custom .mff file can now be used in MapForce (see Importing the .mff File Into MapForce).
Remember that, in order to execute mappings that use native C++ libraries, you will need to
generate C++ code and run the mapping from your C++ code or application.
Resolving C++ compile errors
If you get a compiler error at the line shown below, modify the project properties to include a
reference to the msado15.dll file.
#import "msado15.dll" rename("EOF", "EndOfFile")
In Visual Studio 2008:
1.
2.
3.
4.
On the Tools menu, click Options.
Expand Projects and Solutions > VC++ Directories.
Under "Show directories for", select Include files, and add a new entry that points to the
directory where msado15.dll file is located (usually, C:\Program Files\Common Files
\System\ADO).
Build the project.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
652
8.6.6
Functions
Referencing Java, C# and C++ Libraries Manually
Example: Create a Custom Java Library
This topic describes how to create a sample Java library and configure a .mff file for it so that the
library appears in the Libraries window of MapForce.
1.
2.
Create a new Java project in your preferred development environment (for example,
Eclipse).
Add to the project a new package called com.hello.functions which consists of a
class called Hello. In the code listing below, notice that the HelloFunction function
has been defined as public static.
package com.hello.functions;
public class Hello {
public static String HelloFunction ( boolean greetingType ) {
if( greetingType )
return "Hello World!";
return "Hello User!";
}
}
3.
Optionally, if your project needs support for special schema types such as date, time,
and duration, import the com.altova.types package. To obtain this package, generate
Java code from a mapping without custom functions.
import com.altova.types.*;
4.
5.
Compile your custom library to a class file, and add it to the Java classpath.
Using an XML editor, create a new .mff file and validate it against the ..\Program Files
\MapForceLibraries\mff.xsd folder. Make sure that the text highlighted below points to
the namespace and class defined previously in the Java code. For more information, see
Configuring the .mff File.
<?xml version="1.0" encoding="UTF-8"?>
<mapping version="9" library="helloworld" xmlns:xs="http://
www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance" xsi:noNamespaceSchemaLocation="mff.xsd">
<implementations>
<implementation language="java">
<setting name="namespace" value="com.hello.functions"/>
<setting name="class" value="Hello"/>
</implementation>
</implementations>
<group name="Greetings">
<component name="HelloFunction">
<sources>
<datapoint name="greeting_type" type="xs:boolean"/>
</sources>
<targets>
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Referencing Java, C# and C++ Libraries Manually
653
<datapoint name="result" type="xs:string"/>
</targets>
<implementations>
<implementation language="java">
<function name="HelloFunction"/>
</implementation>
</implementations>
<description>
<short>result = hello(greeting_type)</short>
<long>Returns a greeting according to the given greeting
type.</long>
</description>
</component>
</group>
</mapping>
You have now finished creating a custom library and the .mff file which adapts it to MapForce. The
custom .mff file can now be used in MapForce (see Importing the .mff File Into MapForce).
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
654
8.7
Functions
Regular Expressions
Regular Expressions
MapForce can use regular expressions in the pattern parameter of the match-pattern and
tokenize-regexp functions, to find specific strings.
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
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.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Regular Expressions
655
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.
?
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
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
656
Functions
Regular Expressions
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-insensitive mode.
The regular expression [a-z] plus the i flag would then match all letters a-z and A-Z.
x
If present, whitespace characters are removed from the regular expression 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.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
8.8
Function Library Reference
657
Function Library Reference
This reference chapter describes the MapForce built-in functions available in the Libraries pane,
organized by library.
The availability of function libraries in the Libraries pane depends on the transformation language
you have selected (see Selecting a transformation language ). The core library is a collection of
functions available in C++, C#, Java languages and in at least one of the following: XQuery, XPath,
or XSLT. The lang library is dedicated to functions available in C++, C#, and Java languages.
Other libraries contain functions associated with each separate type of output.
XPath 2.0 restrictions: Several XPath 2.0 functions dealing with sequences are currently not
available.
8.8.1
core | aggregate functions
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 data type 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. 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 (nodes/rows) 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, however, optional.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
658
Functions
Function Library 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.
8.8.1.1
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.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
Argument
Description
parent-context
Optional argument. Supplies the parent context. See also Overriding the
Mapping Context.
values
This argument must be connected to a source item which supplies the
actual data. Note that the supplied argument value must be numeric.
659
For an example of usage, see the mapping GroupTemperaturesByYear.mfd in the
<Documents>\Altova\MapForce2017\MapForceExamples\ directory.
8.8.1.2
count
Returns the number of individual items making up the input sequence. The count of an empty set
is zero. Limited functionality in XSLT1.
8.8.1.3
Argument
Description
parent-context
Optional argument. Supplies the parent context. See also Overriding the
Mapping Context.
nodes/rows
This argument must be connected to the source item to be counted.
max
Returns the maximum value of all numeric values in the input sequence. Note that this function
returns an empty set if the strings argument is an empty set. Not available in XSLT1.
Argument
Description
parent-context
Optional argument. Supplies the parent context. See also Overriding the
Mapping Context.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
660
Functions
Function Library Reference
Argument
Description
values
This argument must be connected to a source item which supplies the
actual data. Note that the supplied argument value must be numeric. To get
the maximum from a sequence of strings, use the max-string function.
For an example of usage, see the mapping GroupTemperaturesByYear.mfd in the
<Documents>\Altova\MapForce2017\MapForceExamples\ directory.
8.8.1.4
max-string
Returns the maximum value of all string values in the input sequence. For example, maxstring("a", "b", "c") returns "c". This function is not available in XSLT1.
Argument
Description
parent-context
Optional argument. Supplies the parent context. See also Overriding the
Mapping Context.
strings
This argument must be connected to a source item which supplies the
actual data. The supplied argument value must be a sequence (zero or
many) of xs:string.
Note that the function returns an empty set if the strings argument is an empty set.
8.8.1.5
min
Returns the minimum value of all numeric values in the input sequence. The minimum of an empty
set is an empty set. Not available in XSLT1.
Argument
Description
parent-context
Optional argument. Supplies the parent context. See also Overriding the
Mapping Context.
values
This argument must be connected to a source item which supplies the
actual data. Note that the supplied argument value must be numeric. To get
the minimum from a sequence of strings, use the min-string function.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
661
For an example of usage, see the mapping GroupTemperaturesByYear.mfd in the
<Documents>\Altova\MapForce2017\MapForceExamples\ directory.
8.8.1.6
min-string
Returns the minimum value of all string values in the input sequence. For example, minstring("a", "b", "c") returns "a". This function is not available in XSLT1.
Argument
Description
parent-context
Optional argument. Supplies the parent context. See also Overriding the
Mapping Context.
strings
This argument must be connected to a source item which supplies the
actual data. The supplied argument value must be a sequence (zero or
many) of xs:string.
Note that the function returns an empty set if the strings argument is an empty set.
8.8.1.7
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
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
662
Functions
Function Library Reference
If you do not supply a delimiter, then the default is an empty string, i.e. no delimiter of any sort.
Result = 2468.
8.8.1.8
sum
Returns the arithmetic sum of all values in the input sequence. The sum of an empty set is zero.
Argument
Description
parent-context
Optional argument. Supplies the parent context. See also Overriding the
Mapping Context.
values
This argument must be connected to a source item which supplies the
actual data. Note that the supplied argument value must be numeric.
See also Example: Summing Node Values.
8.8.2
core | conversion functions
To support explicit data type conversion, several type conversion functions are available in the
conversion library. Note that, in most cases, MapForce creates necessary conversions
automatically and these functions need to be used only in special cases.
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.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
8.8.2.1
Function Library Reference
663
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.
8.8.2.2
format-date
Converts an xs:date input value into a string and formats it according to specified options.
Argument
Description
value
The date to be formatted.
format
A format string identifying the way in which the date is to be formatted. This
argument is used in the same way as the format argument in the formatdateTime function.
language
Optional argument. When supplied, the name of the month and the day of the
week are returned in a specific language. Valid values:
en (default)
English
es
Spanish
de
German
ja
Japanese
In the following example, the output result is: "21 August 2014, Thursday". To translate this value
to Spanish, set the value of the language argument to es.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
664
8.8.2.3
Functions
Function Library Reference
format-dateTime
Converts a date and time value (xs:dateTime) into a string. The string representation of date and
time is formatted according to the value of the format argument.
Argument
Description
value
The xs:dateTime value to be formatted.
format
A format string identifying the way in which value is to be formatted.
language
Optional argument. When supplied, the name of the month and the day of the
week are returned in a specific language. Valid values:
Note:
en (default)
English
es
Spanish
de
German
ja
Japanese
If the function’s output (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 (see Changing the Component Settings).
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.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
665
format := (literal | argument)*
argument := [component(format)?(presentation)?(width)?]
width := , min-width ("-" max-width)?
The components are as follows:
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)
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
z
timezone as a time offset using GMT
GMT+n
The formatting modifier can be one of the following:
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
N
name of component, upper case
MONDAY, TUESDAY
n
name of component, lower case
monday, tuesday
Nn
name of component, title case
Monday, Tuesday
Note:
1)
1)
1)
N, n, and Nn modifiers only support the following components: M, d, D.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
666
Functions
Function Library Reference
The width modifier, if present, is introduced by a comma. It takes the form:
, min-width ("-" max-width)?
The table below illustrates some examples of formatting xs:dateTime values with the help of the
format-dateTime function. The "Value" column specifies the value supplied to the value
argument. The "Format" column specifies the value of the format argument. The "Result" column
illustrates what is returned by the function.
8.8.2.4
Value
Format
Result
2003-1103T00:00:00
[D]/[M]/[Y]
3/11/2003
2003-1103T00:00:00
[Y]-[M,2]-[D,2]
2003-11-03
2003-1103T00:00:00
[Y]-[M,2]-[D,2] [H,2]:[m]:[s]
2003-11-03 00:00:00
2010-0602T08:02
[Y] [MNn] [D01] [F,3-3] [d] [H]:[m]:
[s].[f]
2010 June 02 Wed 153
8:02:12.054
2010-0602T08:02
[Y] [MNn] [D01] [F,3-3] [d] [H]:[m]:
[s].[f] [z]
2010 June 02 Wed 153
8:02:12.054 GMT+02:00
2010-0602T08:02
[Y] [MNn] [D1] [F] [H]:[m]:[s].[f] [Z]
2010 June 2 Wednesday
8:02:12.054 +02:00
2010-0602T08:02
[Y] [MNn] [D] [F,3-3] [H01]:[m]:[s]
2010 June 2 Wed
08:02:12
format-number
Converts a number into a string. The function is available for XSLT 1.0, XSLT 2.0, Java, C#, C++
and Built-in execution engine.
Argument
Description
value
Mandatory argument. Supplies the number to be formatted.
format
Mandatory argument. Supplies a format string that identifies the
way in which the number is to be formatted. This argument is
used in the same way as the format argument in the format-
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
Argument
667
Description
dateTime function.
decimal-point-format
Optional argument. Supplies the character to be used as the
decimal point character. The default value is the full stop ( . )
character.
grouping-separator
Optional argument. Supplies the character used to separate
groups of numbers. The default value is the comma ( , )
character.
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:
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-separator
,
Separates 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.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
668
Functions
Function Library Reference
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. the value gets rounded up if the
fraction is greater than or equal to 0.5. The value gets rounded down if the fraction is less than
0.5. This method of rounding only applies to generated code and the built-in execution engine.
In XSLT 1.0, the rounding mode is undefined. In XSLT 2.0, the rounding mode is "round-half-toeven".
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
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
8.8.2.5
669
format-time
Converts an xs:time input value into a string. The format argument is used in the same way as
the format argument in the format-dateTime function.
E.g
Result: 33-15-12
8.8.2.6
number
Converts an input string into a number. Also converts a boolean input to a number.
8.8.2.7
parse-date
Available for Java, C#, C++, and the Built-in execution engine.
Converts a string into a date, while ignoring the time component. This function uses the parsedateTime function as a basis, while ignoring the time component. The result is of type xs:date.
8.8.2.8
parse-dateTime
Available for Java, C#, C++, and the Built-in execution engine.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
670
Functions
Function Library Reference
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:
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
z
timezone as a time offset using GMT
GMT+n
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
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:
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
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
20110620
[Y,4-4][M,2-2][D,2-2]
2011-06-20T00:00:00
671
Example in MapForce:
Result:
8.8.2.9
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-character
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.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
672
Functions
Function Library Reference
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:
8.8.2.10
parse-time
Available for Java, C#, C++, and the Built-in execution engine.
Converts a string into a time, while ignoring the date component. This function uses the parsedateTime function as a basis, while ignoring the date component. The result is of type xs:time.
8.8.2.11
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.
8.8.3
core | 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.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
8.8.3.1
Function Library Reference
673
get-fileext
Returns the extension of the file path including the dot "." character.
E.g. 'c:\data\Sample.mfd' returns '.mfd'
8.8.3.2
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/'
8.8.3.3
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.
8.8.3.4
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.
8.8.3.5
remove-fileext
Removes the extension of the file path including the dot-character.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
674
Functions
Function Library Reference
E.g. 'c:/data/Sample.mfd' returns 'c:/data/Sample'.
8.8.3.6
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'.
8.8.3.7
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'
8.8.3.8
resolve-filepath
Resolves a relative file path to a relative, or absolute, base folder. The function supports '.' (current
directory) and '..' (parent directory).
For an example, see the mapping MergeMultipleFiles_List.mfd available in the ...
\MapForceExamples folder.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
8.8.4
Function Library Reference
675
core | generator functions
The core / generator functions library includes functions which generate values.
8.8.4.1
auto-number
The auto-number function generates integers in target nodes of a component, depending on the
various parameters you define. The function 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.
Make sure that the result connector (of the auto-number function) is directly connected 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.
global-id
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
676
Functions
Function Library Reference
This parameter allows you to synchronize the number sequence output of two separate autonumber 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 initial 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.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
677
In the example below, start-with and increment are both using the default 1. As soon as the
content of Department changes, i.e. the department name changes, the counter is reset and
starts at 1 for each new department.
8.8.5
core | 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.
input parameters = a | b, or value1 | value2
output parameter = result
The evaluation result of two input nodes depends on the input values as well as the data types
used for the comparison.
For 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.
If the input nodes are of differing types (for example, integer and string, or string and date), then
the data type used for the comparison is the most general (least restrictive) input data type of
the two input types.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
678
Functions
Function Library Reference
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'.
Note:
8.8.5.1
Logical functions cannot be used to test the existence of null values. If you supply a null
value as argument to a logical function, it returns a null value. For more information about
handling null values, see Nil Values / Nillable.
equal
Result is true if a=b, else false.
8.8.5.2
equal-or-greater
Result is true if a is equal/greater than b, else false.
8.8.5.3
equal-or-less
Result is true if a is equal/less than b, else false.
8.8.5.4
greater
Result is true if a is greater than b, else false.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
8.8.5.5
Function Library Reference
679
less
Result is true if a is less than b, else false.
8.8.5.6
logical-and
If both value1 and value2 of the logical-and function are true, then result is true; if different then
false.
8.8.5.7
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. true-false, or
false-true.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
680
8.8.5.8
Functions
Function Library Reference
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.
8.8.5.9
not-equal
Result is true if a is not equal to b.
8.8.6
core | 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.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
681
The example shown above, adds 20% sales tax to each of the articles mapped to the target
component.
8.8.6.1
add
Result is the decimal value of adding value1 to value2.
8.8.6.2
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.
8.8.6.3
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.
8.8.6.4
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.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
682
Functions
Function Library Reference
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.
8.8.6.5
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.
8.8.6.6
multiply
Result is the decimal value of multiplying value1 by value2.
8.8.6.7
round
Returns the value rounded to the nearest integer. When the value is exactly in between two
integers, the "Round Half Towards Positive Infinity" algorithm is used. For example, the value
"10.5" gets rounded to "11", and the value "-10.5" gets rounded to "-10".
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
8.8.6.8
Function Library Reference
683
round-precision
Result is the decimal value of the number rounded to the decimal places defined by "decimals".
In the mapping above, the result is 0.429. For the result to appear correctly in an XML file, make
sure to map it to an element of xs:decimal type.
8.8.6.9
subtract
Result is the decimal value of subtracting value2 from value1.
8.8.7
core | node functions
The node functions allow you to access nodes, or process nodes in a particular way.
8.8.7.1
is-xsi-nil
Returns true (<OrderID>true</OrderID>) if the element node, of the source component, has the
xsi:nil attribute set to "true".
8.8.7.2
node-name
Returns the qualified name (QName) of the connected node. If the node is an XML text() node, an
empty QName is returned. This function only works on those nodes that have a name. If XSLT is
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
684
Functions
Function Library Reference
the target language (which calls fn:node-name), the function 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".
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.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
8.8.7.3
Function Library Reference
685
set-xsi-nil
Sets the target node to xsi:nil.
8.8.7.4
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.
8.8.7.5
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.
8.8.7.6
substitute-missing-with-xsi-nil
For nodes with simple content, this function substitutes any missing (or null values) of the source
component, with the xsi:nil attribute in the target node.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
686
8.8.8
Functions
Function Library Reference
core | QName functions
QName functions provide ways to manipulate the Qualified Names (QName) in XML documents.
8.8.8.1
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.
8.8.8.2
local-name-from-QName
Returns the local name part of the QName.
8.8.8.3
namespace-uri-from-QName
Returns the namespace URI part of the QName.
8.8.9
core | sequence functions
Sequence functions allow processing of input sequences and 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 groupadjacent and group-by
Input parameter bool is of type Boolean for group-starting-with and group-ending-with
The output key is the key of the current group.
8.8.9.1
distinct-values
Allows you to remove duplicate values from a sequence and map the unique items to the target
component.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
687
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.
8.8.9.2
exists
Returns true if the node exists, else returns false.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
688
Functions
Function Library Reference
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.
8.8.9.3
first-items
Returns the first "X" items of the input sequence, where X is the number supplied by the "count"
parameter. E.g. if the value 3 is mapped to the count parameter and a parent node to the nodes/
row parameter, then the first three items will be listed in the output.
8.8.9.4
generate-sequence
Creates a sequence of integers using the "from" and "to" parameters as the boundaries.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
8.8.9.5
Function Library Reference
689
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.
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.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
690
8.8.9.6
Functions
Function Library Reference
group-by
Groups the input sequence nodes/rows into groups of not necessarily adjacent items sharing the
same key. Groups are output in the order the key occurs in the input sequence. 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's first and last names are placed in the Person/First child item.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
691
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 Output button shows the result of the grouping process.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
692
8.8.9.7
Functions
Function Library Reference
group-ending-with
This function groups the input sequence nodes/rows into groups, ending a new group whenever
bool is true. 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.
8.8.9.8
group-into-blocks
Groups the input sequence nodes/rows into blocks of the same size defined by the number
supplied by the block-size parameter.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
8.8.9.9
693
group-starting-with
This function groups the input sequence nodes/rows into groups, starting a new group when bool
is true.
The following example illustrates a sequence of nodes where bool returns true whenever the
node "header" is encountered. Applying the group-starting-with function on this sequence of
nodes results in two groups, as shown below.
Note that the first node in the sequence starts a new group regardless of the value of bool. In
other words, a sequence such as the one below would create three groups.
8.8.9.10
item-at
Returns the nodes/rows at the position supplied by the position parameter. The first item is at
position "1".
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
694
Functions
8.8.9.11
Function Library Reference
items-from-till
Returns a sequence of nodes/rows using the "from" and "till" parameters as the boundaries. The
first item is at position "1".
8.8.9.12
last-items
Returns the last "X" nodes/rows of the sequence where X is the number supplied by the "count"
parameter. The first item is at position "1".
8.8.9.13
not-exists
Returns false if the node exists, else returns true.
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:
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.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
695
The two XML instance files are shown below, the differences between them are:
a.xml (left) contains the node <b kind="3">, which is missing from b.xml.
b.xml (right) contains the node <b kind="4"> which is missing from a.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.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
696
Functions
8.8.9.14
Function Library Reference
position
Returns the position of a node inside its containing 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.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
697
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.
What this mapping does is to output:
The second Person in each Department
of each Office in Altova.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
698
Functions
Function Library Reference
Finding the position of items in a filtered sequence:
As the filter component is not a sequence function, it cannot be used directly in conjunction with
the position function to find the position of filtered items. To do this you have to use the "Variable"
component.
The results of a Variable component are always sequences, i.e. a delimited list of values, which
can also be used to create sequences.
The variable component is used 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
The position function then numbers these contacts sequentially
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
8.8.9.15
699
replicate-item
Repeats every item in the input sequence the number of times specified in the count argument. If
you connect a single item to the node/row argument, the function returns N items, where N is the
value of the count argument. If you connect a sequence of items to the node/row argument, the
function repeats each individual item in the sequence count times, processing one item at a time.
For example, if count is 2, then the sequence (1,2,3) produces (1,1,2,2,3,3).
Note that you can supply a different count value for each item. For example, let's assume that
you have a source XML file with the following structure:
<?xml version="1.0" encoding="UTF-8"?>
<SourceList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="source.xsd">
<person>
<name>Michelle</name>
<count>2</count>
</person>
<person>
<name>Ted</name>
<count>4</count>
</person>
<person>
<name>Ann</name>
<count>3</count>
</person>
</SourceList>
With the help of the replicate-item function, you can repeat each person name a different
number of times in a target component. To achieve this, connect the <count> node of each
person to the count input of the replicate-item function:
The output is as follows:
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
700
Functions
Function Library Reference
<?xml version="1.0" encoding="UTF-8"?>
<TargetLists xsi:noNamespaceSchemaLocation="target.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<TargetList>
<TargetString>Michelle</TargetString>
<TargetString>Michelle</TargetString>
</TargetList>
<TargetList>
<TargetString>Ted</TargetString>
<TargetString>Ted</TargetString>
<TargetString>Ted</TargetString>
<TargetString>Ted</TargetString>
</TargetList>
<TargetList>
<TargetString>Ann</TargetString>
<TargetString>Ann</TargetString>
<TargetString>Ann</TargetString>
</TargetList>
</TargetLists>
8.8.9.16
replicate-sequence
Repeats all items in the input sequence the number of times specified in the count argument. For
example, if count is 2, then the sequence (1,2,3) produces (1,2,3,1,2,3).
8.8.9.17
set-empty
Returns an empty sequence.
8.8.9.18
skip-first-items
Skips the first "X" items/nodes of the input sequence, where X is the number supplied by the
"count" parameter, and returns the rest of the sequence.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
8.8.9.19
701
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.
8.8.10
core | 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.
8.8.10.1
char-from-code
Result is the character representation of the decimal Unicode value of value.
For an example, see Replacing Special Characters.
8.8.10.2
code-from-char
Result is the decimal Unicode value of the first character of value.
8.8.10.3
concat
Concatenates (appends) two or more values into a single result string. All input values are
automatically converted to type string.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
702
Functions
8.8.10.4
Function Library Reference
contains
Result is true if data supplied to the value parameter contains the string supplied by the substring
parameter.
8.8.10.5
normalize-space
Result is the normalized input string, i.e. leading and trailing spaces are removed, then each
sequence of multiple consecutive whitespace characters are replaced by a single whitespace
character. The Unicode character for "space" is (U+0020).
8.8.10.6
starts-with
Result is true if the input string "string" starts with substr, else false.
8.8.10.7
string-length
Result is the number of characters supplied by the string parameter.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
8.8.10.8
703
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.
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.
8.8.10.9
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.
8.8.10.10
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.
8.8.10.11
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.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
704
Functions
Function Library Reference
E.g. Input string is A,B,C and delimiter is "," - then result is A B C.
Example
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.
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
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
705
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.
8.8.10.12
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.
Example
The tokenizeString2.mfd file available in the ...\MapForceExamples folder shows how the
tokenize-by-length function is used.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
706
Functions
Function Library Reference
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.
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 further to the
input parameter of the tokenize-by-length function.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
707
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 component.
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:
8.8.10.13
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.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
708
Functions
Function Library Reference
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, see Regular expressions.
8.8.10.14
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.
E.g.
input string is 123145
(search) string1 is 15
(replace) string2 is xy
So:
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
709
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"
8.8.11
db
The db library contains functions that allow you to define the mapping results when encountering
null fields in databases.
8.8.11.1
is-not-null
Returns false if the field is null, otherwise returns true.
8.8.11.2
is-null
Returns true if the field is null, otherwise returns false.
8.8.11.3
set-null
Used to set a database column to null. This function will also overwrite a default value with null. If
connected to something else i.e. not a database field, it will behave like an empty sequence.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
710
Functions
Function Library Reference
Please note:
Connecting set-null to a different function will usually result in the other function not being
called at all. Connecting set-null to a sequence function, e.g. count, will call the function
with an empty sequence.
Connecting to special functions, Filters and IF-Else conditions works as expected, fields
are set to null. For filters this means the "node/row" input.
Using set-null as an input for a simpleType element will not create that element in the
target component.
8.8.11.4
substitute-null
Used to map the current field content if it exists, otherwise use the item mapped to the replacewith parameter.
The image below shows an example of the substitute-null function in use, and is available as "DBApplicationList" in the ...\MapForceExamples folder.
The first function checks if a Category entry exists in the Applications table. As one does not
exist for the Notepad application, "Misc" is mapped to the Category item of the Text file.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
711
The second function checks if a Description entry exist, and maps the string "No description" if
one does not exist, which is also the case with the Notepad application.
8.8.12
lang | QName functions
The lang library contains functions that are available when selecting either Java, C#, or C++
languages.
8.8.12.1
QName-as-string
Result is the unique string representation of the QName.
8.8.12.2
string-as-QName
Converts the string representation of a QName back to a QName.
8.8.13
lang | datetime functions
The lang library contains functions that are available when selecting either Java, C#, or C++
languages.
8.8.13.1
age
age
Result is the age of the person in full years. The now argument is optional and the default is the
current system date. The result is then the full amount of years between the birthdate and now. If
a value is mapped to the now argument, the result is the difference between the two dates in full
years.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
712
Functions
8.8.13.2
Function Library Reference
convert-to-utc
Converts the local "time" input parameter into Coordinated Universal Time, or GMT/Zulu time.
(The function takes the timezone component, e.g. +5:00, into account).
E.g. Instance document datetime:
departuredatetime="2001-12-17T09:30:02+05:00"
Result:
departuredatetime="2001-12-17T04:30:02"
Please note:
If the source dateTime is in the form departuredatetime="2001-12-17T09:30:02Z" then no
conversion will take place because the trailing "Z" defines this time to be Zulu time, i.e. UTC. The
result will be departuredatetime="2001-12-17T09:30:02".
8.8.13.3
date-from-datetime
Result is the date part of a datetime input argument. The time part of the dateTime, starting with T
in the instance document, is set to zero. Note that the timezone increment is not changed.
E.g. Instance document datetime:
departuredatetime="2001-12-17T09:30:02+05:00"
Result:
departuredatetime="2001-12-17T00:00:00+05:00"
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
8.8.13.4
713
datetime-add
Result is the datetime obtained by adding a duration (second argument) to a datetime (first
argument).
Durations must be entered in the form: P1Y2M3DT04H05M. Periods can be made negative by
adding the minus character before the P designator, e.g. -P1D.
P is the period designator, and is mandatory; the rest of above period is therefore:
1 Year, 2 Months, 3 Days T(ime designator), 04 Hours, 05 Minutes.
The example shown below, adds 10 days to the departuredatetime, i.e. P10D.
E.g. Instance document datetime:
departuredatetime="2001-12-17T09:30:02+05:00"
Result:
departuredatetime="2001-12-27T09:30:02+05:00"
To extract yesterdays date from dateTime input:
Use the "now" function to input the current date/time including timezone. A period can be made
negative by using the minus character before the P designator, e.g. -P1D (minus 1 day).
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
714
Functions
Function Library Reference
E.g. datetime now is 28th Feb 2012, 17:19:54.748(millisec)+01timezone.
now="2012-02-28T17:19:54.748+01:00"
Result:
departuredatetime="2012-02-27T17:19:54.748+01:00"
i.e. 27th Feb 2012, 17:19:54.748(millisec)+01timezone
8.8.13.5
datetime-diff
Result is the duration obtained by subtracting datetime2 (second argument) from datetime1 (first
argument). The result can be mapped to a string, or duration, datatype.
Note that the arrivaldatetime has been connected to datetime1 and departuredatetime to
datetime2.
E.g. We want to find the difference, as a duration, between the departure and arrival times.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
715
datetime1 arrivaldatetime="2001-12-17T19:30:02+05:00"
datetime2 departuredatetime="2001-12-17T09:30:02+05:00"
Result: the difference between the two is 10 hours:
result= PT10H
8.8.13.6
datetime-from-date-and-time
Result is a datetime built from a datevalue (first argument) and a timevalue (second argument).
The first argument must be of type xs:date and the second xs:time. The result can be mapped to
a sting or dateTime datatype.
E.g.
date="2012-06-29"
time="11:59:55"
Result:
dateTime="2012-06-29T11:59:55"
8.8.13.7
datetime-from-parts
Result is a datetime built from any combination of the following parts as arguments: year, month,
day, hour, minute, second, millisecond, and timezone. This function automatically normalizes the
supplied parameters e.g. 32nd of January will automatically be changed to 1st February.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
716
Functions
Function Library Reference
All of the arguments are of type xs:int except for millisecond, which is of type xs:decimal. The
datetime result parameter is of type xs:dateTime.
The date and time fields are supplied by the IDOC instance file:
IDOC:Date
ICOC:Time
Result
8.8.13.8
19990621
0930
1999-06-21T09:30:00
day-from-datetime
Result is the day from the datetime argument.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
717
E.g.
datetime="2001-12-17T10:30:03+01:00"
Result: 17
8.8.13.9
day-from-duration
Result is the day from the duration argument.
E.g.
duration="P1Y2M3DT10H30M"
Result: 3
8.8.13.10
duration-add
Result is the duration obtained by adding two durations.
E.g.
duration1="P0Y0M3DT03H0M" (3days 3 hours)
duration2="P0Y0M3DT01H0M" (3days 1 hour)
Result: P6DT4H (6days 4 hours)
8.8.13.11
duration-from-parts
Result is a duration calculated by combining the following parts supplied as arguments: year,
month, day, hour, minute, second, millisecond, negative.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
718
Functions
Function Library Reference
Durations are in the form P1Y2M3DT04H05M06.07S i.e. P(eriod) 1 Year, 2 Months, 3 Days, T(ime
designator), 04 Hours, 05 Minutes, 06.07 seconds.milliseconds.
All of the arguments are of type xs:int except for millisecond, which is of type xs:decimal, and
negative, which is of type xs:boolean (i.e. 1 for true, 0 for false). The duration parameter is of type
xs:duration.
Parts: 1971 year, 11 month, 19 day, 11 hour, 05 minutes, 15.06 seconds, negative period "false".
Result:
duration="P1971Y11M19DT11H5M15.00006S"
8.8.13.12
duration-subtract
Result is the duration obtained by subtracting duration2 from duration1.
Durations must be entered in the form: P1Y2M3DT04H05M. Periods can be made negative by
using the minus character before the P designator, e.g. -P1D.
P is the period designator, and is mandatory; the rest of period is therefore:
1 Year, 2 Months, 3 Days T(ime designator), 04 Hours, 05 Minutes.
The example shown below, subtracts 1 hour from flighttime, i.e. PT1H.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
719
E.g.
duration1="P0Y0M0DT05H07M"
duration2="PT1H"
Result: PT4H7M
8.8.13.13
hour-from-datetime
Result is the hour part of the datetime argument.
E.g.
datetime="2001-12-17T09:30:02+05:00"
hour= 9
8.8.13.14
hour-from-duration
Result is the hour component of the duration argument.
E.g.
duration="P0Y0M0DT05H07M"
hour= 5
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
720
Functions
8.8.13.15
Function Library Reference
leapyear
Result is true or false depending on whether the year of the supplied dateTime is in a leap year.
E.g.
arrivaldatetime="2001-12-17T19:30:02+05:00"
result="false"
8.8.13.16
millisecond-from-datetime
Result is the millisecond part of the datetime argument.
E.g.
datetime="2001-12-17T09:30:02.544+05:00"
millisecond= 544
8.8.13.17
millisecond-from-duration
Result is the millisecond component of the duration argument.
E.g.
duration="P0Y0M0DT05H07M02.227S"
millisecond= 227
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
8.8.13.18
721
minute-from-datetime
Result is the minute part of the datetime argument.
E.g.
datetime="2001-12-17T09:30:02.544+05:00"
minute= 30
8.8.13.19
minute-from-duration
Result is the minute component of the duration argument.
E.g.
duration="P0Y0M0DT05H07M02.227S"
minute= 7
8.8.13.20
month-from-datetime
Result is the month part of the dateTime argument.
E.g.
datetime="2001-12-17T09:30:02.544+05:00"
month= 12
8.8.13.21
month-from-duration
Result is the month component of the duration argument.
E.g.
duration="P0Y04M0DT05H07M02.227S"
month= 4
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
722
Functions
8.8.13.22
Function Library Reference
now
Result is the current dateTime (including timezone).
E.g.
result= 2012-03-06T14:44:57.567+01:00
For an example on how to extract yesterday's date, see the core | lang | datetime-add function.
8.8.13.23
remove-timezone
Removes the timezone component, e.g. +5:00, from the time input parameter.
E.g.
departuredatetime="2001-12-17T09:30:02+05:00"
time: 2001-12-17T09:30:02
8.8.13.24
second-from-datetime
Result is the seconds part of the dateTime argument.
E.g.
datetime="2001-12-17T09:30:02.544+05:00"
second= 2
8.8.13.25
second-from-duration
Result is the seconds component of the duration argument.
E.g.
duration="P0Y04M0DT05H07M02.227S"
second= 2
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
8.8.13.26
723
time-from-datetime
Result is the time part of the dateTime argument.
E.g.
datetime="2001-12-17T09:30:02.544+05:00"
time= 09:31:02+05:00
8.8.13.27
timezone
Returns the timezone (i.e. +05:00 here) relative to UTC of the dateTime value. NB timezone unit
is minutes.
E.g.
datetime="2001-12-17T09:30:02.544+05:00"
timezone= 300
8.8.13.28
weekday
Returns the weekday of the dateTime value, starting with Monday=1 to Sunday=7.
E.g.
datetime="2001-12-17T09:30:02.544+05:00"
weekday= 1
8.8.13.29
weeknumber
Returns the week number within the year specified by the dateTime value.
E.g.
datetime="2001-12-17T09:30:02.544+05:00"
weeknumber= 51
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
724
Functions
8.8.13.30
Function Library Reference
year-from-datetime
Result is the year part of the dateTime argument.
E.g.
datetime="2001-12-17T09:30:02.544+05:00"
year= 2001
8.8.13.31
year-from-duration
Result is the year component of the duration argument.
E.g.
duration="P01Y04M0DT05H07M02.227S"
year= 1
8.8.14
lang | generator functions
The lang library contains functions that are available when selecting either Java, C#, or C++
languages. The generator functions generate values for database fields, which do not have any
input data from the Schema, database or EDI source component.
8.8.14.1
create-guid
Result is a globally-unique identifier (as a hex-encoded string) for the specific field.
8.8.15
lang | logical functions
The lang library contains functions that are available when selecting either Java, C#, or C++
languages.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
8.8.15.1
725
logical-xor
Result is true if value1 is different than value2, otherwise false.
8.8.15.2
negative
Result is true if value is negative, i.e. less than zero, otherwise false.
8.8.15.3
numeric
Result is true if value is a number, otherwise false. The input will usually be a string.
8.8.15.4
positive
Result is true if value is positive, i.e. equal to or greater than zero, otherwise false.
8.8.16
lang | math functions
The lang library contains functions that are available when selecting either Java, C#, or C++
languages.
8.8.16.1
abs
Result is the absolute value of the input value.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
726
Functions
8.8.16.2
Function Library Reference
acos
Result is the arc cosine of value.
8.8.16.3
asin
Result is the arc sine of value.
8.8.16.4
atan
Result is the arc tangent of value.
8.8.16.5
cos
Result is the cosine of value.
8.8.16.6
degrees
Result is the conversion of value in radians into degrees.
8.8.16.7
divide-integer
Result is the integer result of dividing value1 by value2. E.g. 15 divide-integer 2, integer result is
7.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
8.8.16.8
727
exp
Result is e (base natural logarithm) raised to the value th power.
8.8.16.9
log
Result is the natural logarithm of value.
8.8.16.10
log10
Result is logarithm (base 10) of value.
8.8.16.11
max
Result is the numerically larger value of value1 compared to value2.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
728
Functions
8.8.16.12
Function Library Reference
min
Result is the numerically smaller value of value1 compared to value2.
8.8.16.13
pi
Result is the value of pi.
8.8.16.14
pow
Result is the value of a raised to the power bth power.
8.8.16.15
radians
Result is the conversion of value in degrees to radians.
8.8.16.16
random
Result is a pseudorandom value between 0.0 and 1.0
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
8.8.16.17
729
sin
Result is the sine of value.
8.8.16.18
sqrt
Result is the square root of value.
8.8.16.19
tan
Result is the tangent of value.
8.8.16.20
unary-minus
Result is the negation of the signed input value. E.g. +3 result is -3, while -3 result is 3.
8.8.17
lang | string functions
The lang library contains functions that are available when selecting either Java, C#, or C++
languages.
8.8.17.1
capitalize
Result is the input string value, where the first letter of each word is capitalized (initial caps).
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
730
Functions
8.8.17.2
Function Library Reference
count-substring
Result is the number of times that substr occurs in string.
8.8.17.3
empty
Result is true if the input string value is empty, otherwise false.
8.8.17.4
find-substring
Returns the position of the first occurrence of substr. within string, starting at position startindex.
The first character has position 1. If the substring could not be found, then the result is 0.
8.8.17.5
format-guid-string
Result is a correctly formatted GUID string formatted_guid, using unformatted_guid as the
input string, for use in database fields. See also the create-guid function in the lang | generator
functions library.
8.8.17.6
left
Result is a string containing the first number characters of string.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
731
E.g. string="This is a sentence" and number=4, result is "This".
8.8.17.7
left-trim
Result is the input string with all leading whitespace characters removed.
8.8.17.8
lowercase
Result is the lowercase version of the input string. For Unicode characters the corresponding
lower-case characters (defined by the Unicode consortium) are used.
8.8.17.9
match-pattern
Result is true if the input string matches the regular expression defined by pattern, else false.
The specific regular expression syntax depends on the target language (see also Regular
expressions ).
8.8.17.10
pad-string-left
Returns a string which is padded to the left by a single specific character, up to a required length.
The desired string length and the padding character are supplied as arguments.
string
Specifies the input string.
desired-length
Defines the desired length of the string after padding.
padding-char
Defines the character to use as padding character.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
732
Functions
8.8.17.11
Function Library Reference
pad-string-right
Returns a string which is padded to the right by a single specific character, up to a required
length. The desired string length and the padding character are supplied as arguments.
string
Specifies the input string.
desired-length
Defines the desired length of the string after padding.
padding-char
Defines the character to use as padding character.
8.8.17.12
repeat-string
Repeats the string supplied as argument n times. The count argument specifies the number of
times to repeat the string.
8.8.17.13
replace
Result is a new string where each instance of oldstring, in the input string value, is replaced by
newstring.
For an example, see Replacing Special Characters.
8.8.17.14
reversefind-substring
Returns the position of the first occurrence of substr. within string, starting at position endindex,
i.e. from right to left. The first character has position 1. If the substring could not be found, then
the result is 0.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
8.8.17.15
733
right
Result is a string containing the last number characters of string.
E.g. string="This is a sentence" and number=5, result is "tence".
8.8.17.16
right-trim
Result is the input string with all trailing whitespace characters removed.
8.8.17.17
string-compare
Returns the result of a string comparison of string1 with string2 taking case into account. If
string1=string2 then result is 0.
If string1 is smaller than string2 then result is < 0.
If string1 is larger than string2 then result is > 0
8.8.17.18
string-compare-ignore-case
Returns the result of a string comparison of string1 with string2 ignoring case. If string1=string2
then result is 0.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
734
Functions
Function Library Reference
If string1 is smaller than string2 then result is < 0.
If string1 is larger than string2 then result is > 0.
8.8.17.19
uppercase
Result is the string input converted into uppercase. For Unicode characters the corresponding
upper-case characters (defined by the Unicode consortium) are used.
8.8.18
xpath2 | accessors
XPath2 functions are available when either the XSLT2 or XQuery languages are selected.
8.8.18.1
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.
8.8.18.2
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).
8.8.18.3
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.)
8.8.19
xpath2 | anyURI functions
XPath2 functions are available when either the XSLT2 or XQuery languages are selected.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
8.8.19.1
735
resolve-uri
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.
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:
8.8.20
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 the second argument
is not supplied.
xpath2 | boolean functions
XPath2 functions are available when either the XSLT2 or XQuery languages are selected.
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.
8.8.20.1
false
Returns the Boolean value "false".
8.8.20.2
true
Returns the Boolean value "true".
8.8.21
xpath2 | constructors
XPath2 functions are available when either the XSLT2 or XQuery languages are selected.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
736
Functions
Function Library Reference
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: YYYY-MM-DD
(screenshot below).
In the screenshot above, a string constant (2009-08-22) has been used to provide the input
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.
8.8.22
xpath2 | context functions
XPath2 functions are available when either the XSLT2 or XQuery languages are selected.
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.
8.8.22.1
current-date
Returns the current date (xs:date) from the system clock.
8.8.22.2
current-dateTime
Returns the current date and time (xs:dateTime) from the system clock.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
8.8.22.3
737
current-time
Returns the current time (xs:time) from the system clock.
8.8.22.4
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.
8.8.22.5
implicit-timezone
Returns the value of the "implicit timezone" property from the evaluation context.
8.8.22.6
last
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
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.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
738
Functions
Function Library Reference
We would advise you to use the position and count functions from the core library.
8.8.23
xpath2 | durations, date and time functions
XPath2 functions are available when either the XSLT2 or XQuery languages are selected.
The XPath 2 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).
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
739
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-from-duration 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 functions 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.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
740
8.8.24
Functions
Function Library Reference
xpath2 | node functions
The following XPath 2 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.
2.
3.
4.
In the source schema, the Language element has an xml:lang attribute.
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).
The Language node is the context node at the point where the en element is created in
the output document.
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 localname 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.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
741
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.
8.8.25
xpath2 | numeric functions
The following XPath 2 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.
8.8.26
xpath2 | string functions
The following XPath 2 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.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
742
Functions
Function Library Reference
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 (escapereserved) 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.
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,
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
743
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.
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.
8.8.27
xslt | 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.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
744
Functions
Function Library Reference
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.
2.
3.
4.
In the source schema, the Language element has an xml:lang attribute.
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).
The Language node is the context node at the point where the en element is created in
the output document.
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 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.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
745
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 Language 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.
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".
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
746
Functions
Note:
8.8.28
Function Library Reference
Additional XPath 1.0 functions can be found in the Core function library.
xslt | xslt functions
The functions in the XSLT Functions library are XSLT 1.0 functions.
8.8.28.1
currrent
The current function takes no argument and returns the current node.
8.8.28.2
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.
8.8.28.3
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 2017 Professional Edition
© 2017 Altova Gmb H
Functions
Function Library Reference
747
The function returns a boolean.
8.8.28.4
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.
8.8.28.5
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.
8.8.28.6
system-property
The system-property function returns properties of the XSLT processor (the system). Three
system 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.
© 2017 Altova Gmb H
Altova MapForce 2017 Professional Edition
748
Functions
8.8.28.7
Function Library Reference
unparsed-enity-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 2017 Professional Edition
© 2017 Altova Gmb H
Chapter 9
Automating Mappings and MapForce
750
Automating Mappings and MapForce
9
Automating Mappings and MapForce
This section describes the command line interface of MapForce and ways to automate mapping
execution with Altova server tools: RaptorXML Server, MapForce Server, and FlowForce Server.
Altova MapForce 2017 Professional Edition
© 2017 Altova Gmb H
Automating Mappings and MapForce
9.1
About MapForce Server
751
About MapForce Server
MapForce Server i