Altova MapForce 2008

User and Reference Manual
Altova MapForce 2008 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: 2008
© 2008 Altova GmbH
Table of Contents
1
MapForce 2008
3
2
What's new in MapForce Version 2008 R2
6
2.1
What's new in MapForce
.................................................................................................................
Version 2008
7
2.2
.................................................................................................................
8
What's new in MapForce
Version 2007 R3
3
MapForce overview
3.1
Terminology ................................................................................................................. 12
3.2
MapForce components
................................................................................................................. 15
3.3
Functions and.................................................................................................................
libraries
18
3.3.1
Function context
menu
...................................................................................................
20
3.4
Mapping between
.................................................................................................................
components
21
3.4.1
Missing items................................................................................................... 23
3.5
Validating mappings
.................................................................................................................
and mapping output
27
3.6
29
XSLT, Output.................................................................................................................
tab - generating XSLT
3.7
30
Loops, groups.................................................................................................................
and hierarchies
4
MapForce tutorial
4.1
Setting up the .................................................................................................................
mapping environment
34
4.2
Mapping schema
.................................................................................................................
items
37
4.3
.................................................................................................................
40
Using functions
to map data
4.4
Filtering data ................................................................................................................. 44
4.5
Generating XSLT
.................................................................................................................
1.0 and 2.0 code
48
4.6
Multiple target.................................................................................................................
schemas / documents
50
4.6.1
Viewing and generating
multiple target schema output
...................................................................................................
53
4.7
Mapping multiple
.................................................................................................................
source items, to single target items
55
4.7.1
Creating the mappings
................................................................................................... 56
4.7.2
Duplicating input
...................................................................................................
items
59
Altova MapForce 2008
10
32
1
5
Methods of mapping data (Standard / Mixed /
Copy All)
66
5.1
67
Source driven.................................................................................................................
/ mixed content mapping
5.2
.................................................................................................................
70
Default settings:
mapping mixed content
5.3
Mixed content.................................................................................................................
example
74
5.4
Source-driven.................................................................................................................
/ mixed content vs. standard mapping
76
5.5
................................................................................................................. 78
Copy-all connections
5.6
................................................................................................................. 81
Connector properties
6
Global Resources
6.1
Global Resources
.................................................................................................................
- Files
87
6.1.1
Defining / Adding
...................................................................................................
global resources
88
6.1.2
Assigning a global
...................................................................................................
resource
91
6.1.3
Using / activating
...................................................................................................
a global resource
92
6.2
.................................................................................................................
94
Global Resources
- Folders
6.3
.................................................................................................................
97
Global Resources
- Application workflow
6.3.1
Start application
...................................................................................................
workflow
101
6.4
.................................................................................................................
104
Global Resources
- Properties
7
How To... Filter, Transform, Aggregate
7.1
Value-Map -.................................................................................................................
transforming input data
109
7.1.1
Value-Map component
...................................................................................................
properties
112
7.2
Aggregate functions:
.................................................................................................................
min, max, sum
114
7.3
Mappings and
.................................................................................................................
root element of target documents
116
7.4
.................................................................................................................
117
Boolean values
and XSLT 1.0
7.5
.................................................................................................................
119
Boolean comparison
of input nodes
7.6
Priority Context
................................................................................................................. 120
7.7
Command line
.................................................................................................................
parameters
121
7.8
122
Input values,.................................................................................................................
overrides and command line parameters
7.9
125
Node testing,.................................................................................................................
exists / not-exist
7.9.1
Mapping missing
...................................................................................................
nodes - using Not-exists
127
86
108
129
7.10 Using DTDs .................................................................................................................
as "schema" components
7.11 Type conversion
.................................................................................................................
checking
130
7.12 MapForce Exceptions
................................................................................................................. 131
2
Altova MapForce 2008
8
Defining User-defined functions
134
8.1
.................................................................................................................
138
Inline vs. Standard
user-defined functions
8.2
.................................................................................................................
140
Standard user-defined
function
8.3
Complex user-defined
.................................................................................................................
function - XML node as input
144
8.3.1
Complex input
...................................................................................................
components - defining
145
8.4
Complex user-defined
.................................................................................................................
function - XML node as output
149
8.4.1
Complex output
...................................................................................................
components - defining
150
8.5
User-defined.................................................................................................................
function - example
154
9
Adding custom XSLT and XQuery functions
9.1
Adding custom
.................................................................................................................
XSLT 1.0 functions
163
9.2
.................................................................................................................
166
Adding custom
XSLT 2.0 functions
9.3
.................................................................................................................
167
Aggregate functions
- summing nodes in XSLT1 and 2
10
MapForce Reference
162
172
10.1 File
................................................................................................................. 173
10.2 Edit
................................................................................................................. 175
10.3 Insert
................................................................................................................. 176
10.4 Component ................................................................................................................. 177
10.5 Connection ................................................................................................................. 180
10.6 Function
................................................................................................................. 182
10.7 Output
................................................................................................................. 184
10.8 View
................................................................................................................. 185
10.9 Tools
................................................................................................................. 186
10.10 Help Menu ................................................................................................................. 189
10.10.1 Table of Contents,
Index, Search
...................................................................................................
190
10.10.2 Activation, Order
...................................................................................................
Form, Registration, Updates
191
10.10.3 Other Commands
................................................................................................... 192
11
The MapForce API
194
11.1 Overview ................................................................................................................. 195
11.1.1 Object model................................................................................................... 196
11.1.2 Example: Code-Generation
................................................................................................... 197
11.1.3 Example: Project
Support
...................................................................................................
199
11.1.4 Error handling
................................................................................................... 203
Altova MapForce 2008
3
................................................................................................................. 205
11.2 Object Reference
11.2.1 Application ................................................................................................... 206
Events ........................................................................................................... 207
.......................................................................................................................... 207
OnDocumentOpened
.......................................................................................................................... 207
OnProjectOpened
11.2.2
11.2.3
........................................................................................................... 207
ActiveDocument
........................................................................................................... 207
ActiveProject
........................................................................................................... 207
Application
........................................................................................................... 208
Documents
........................................................................................................... 208
HighlightSerializedMarker
Name ........................................................................................................... 208
........................................................................................................... 208
NewDocument
........................................................................................................... 209
NewProject
........................................................................................................... 209
OpenDocument
........................................................................................................... 209
OpenProject
........................................................................................................... 209
OpenURL
Options........................................................................................................... 209
Parent ........................................................................................................... 210
Project ........................................................................................................... 210
Quit ........................................................................................................... 210
Visible ........................................................................................................... 210
........................................................................................................... 211
WindowHandle
MapForceView
................................................................................................... 212
Active ........................................................................................................... 212
........................................................................................................... 212
Application
........................................................................................................... 212
HighlightMyConnections
........................................................................................................... 213
HighlightMyConnectionsRecursivey
........................................................................................................... 213
InsertXMLFile
........................................................................................................... 213
InsertXMLSchema
........................................................................................................... 213
InsertXMLSchemaWithSample
Parent ........................................................................................................... 214
........................................................................................................... 214
ShowItemTypes
........................................................................................................... 214
ShowLibraryInFunctionHeader
Document ................................................................................................... 215
Events ........................................................................................................... 215
.......................................................................................................................... 215
OnDocumentClosed
.......................................................................................................................... 215
OnModifiedFlagChanged
Activate........................................................................................................... 216
........................................................................................................... 216
Application
Close ........................................................................................................... 216
........................................................................................................... 216
FullName
........................................................................................................... 216
GenerateCHashCode
4
Altova MapForce 2008
11.2.4
11.2.5
11.2.6
11.2.7
Altova MapForce 2008
........................................................................................................... 217
GenerateCppCode
........................................................................................................... 217
GenerateCodeEx
........................................................................................................... 217
GenerateJavaCode
........................................................................................................... 218
GenerateOutput
........................................................................................................... 218
GenerateXQuery
........................................................................................................... 218
GenerateXSLT
........................................................................................................... 218
GenerateXSLT2
........................................................................................................... 219
HighlightSerializedMarker
........................................................................................................... 219
JavaSettings_BasePackageName
........................................................................................................... 219
MapForceView
Name ........................................................................................................... 220
........................................................................................................... 220
OutputSettings_ApplicationName
........................................................................................................... 220
OutputSettings_Encoding
Parent ........................................................................................................... 220
Path ........................................................................................................... 220
Save ........................................................................................................... 221
SaveAs ........................................................................................................... 221
Saved ........................................................................................................... 221
Documents ................................................................................................... 222
........................................................................................................... 222
Application
Parent ........................................................................................................... 222
Count ........................................................................................................... 222
Item ........................................................................................................... 222
........................................................................................................... 223
NewDocument
........................................................................................................... 223
OpenDocument
........................................................................................................... 223
ActiveDocument
ErrorMarkers................................................................................................... 224
........................................................................................................... 224
Application
Count ........................................................................................................... 224
Item ........................................................................................................... 224
Parent ........................................................................................................... 224
ErrorMarker................................................................................................... 226
........................................................................................................... 226
Application
........................................................................................................... 226
DocumentFileName
........................................................................................................... 226
ErrorLevel
........................................................................................................... 226
Highlight
........................................................................................................... 227
Serialization
Text ........................................................................................................... 227
Parent ........................................................................................................... 227
Options
................................................................................................... 228
........................................................................................................... 228
Application
5
11.2.8
........................................................................................................... 228
CodeDefaultOutputDirectory
........................................................................................................... 228
CompatibilityMode
........................................................................................................... 229
CppSettings_DOMType
........................................................................................................... 229
CppSettings_GenerateVC6ProjectFile
........................................................................................................... 229
CppSettings_GenerateVSProjectFile
........................................................................................................... 230
CppSettings_LibraryType
........................................................................................................... 230
CppSettings_UseMFC
........................................................................................................... 230
CSharpSettings_ProjectType
........................................................................................................... 230
DefaultOutputEncoding
Parent ........................................................................................................... 231
........................................................................................................... 231
ShowLogoOnPrint
........................................................................................................... 231
ShowLogoOnStartup
........................................................................................................... 231
UseGradientBackground
........................................................................................................... 232
XSLTDefaultOutputDirectory
Project (Enterprise
...................................................................................................
or Professional Edition)
233
........................................................................................................... 233
_NewEnum
.......................................................................................................................... 234
Events
.........................................................................................................................................
OnProjectClosed
234
11.2.9
6
........................................................................................................... 234
AddActiveFile
AddFile........................................................................................................... 235
........................................................................................................... 235
Application
Close ........................................................................................................... 235
Count ........................................................................................................... 235
........................................................................................................... 236
CreateFolder
........................................................................................................... 236
FullName
........................................................................................................... 236
GenerateCode
........................................................................................................... 236
GenerateCodeEx
........................................................................................................... 236
GenerateCodeIn
........................................................................................................... 237
GenerateCodeInEx
........................................................................................................... 237
InsertWebService
Item ........................................................................................................... 237
........................................................................................................... 238
Java_BasePackageName
Name ........................................................................................................... 238
........................................................................................................... 238
Output_Folder
........................................................................................................... 238
Output_Language
........................................................................................................... 239
Output_TextEncoding
Parent ........................................................................................................... 239
Path ........................................................................................................... 239
Save ........................................................................................................... 239
Saved ........................................................................................................... 239
ProjectItem (Enterprise
...................................................................................................
or Professional Edition)
241
Altova MapForce 2008
........................................................................................................... 241
_NewEnum
........................................................................................................... 242
AddActiveFile
AddFile........................................................................................................... 242
........................................................................................................... 242
Application
........................................................................................................... 242
CodeGenSettings_Language
........................................................................................................... 243
CodeGenSettings_OutputFolder
........................................................................................................... 243
CodeGenSettings_UseDefault
Count ........................................................................................................... 243
........................................................................................................... 243
CreateFolder
........................................................................................................... 244
CreateMappingForProject
........................................................................................................... 244
GenerateCode
........................................................................................................... 244
GenerateCodeEx
........................................................................................................... 245
GenerateCodeIn
........................................................................................................... 245
GenerateCodeInEx
Item ........................................................................................................... 245
Kind ........................................................................................................... 245
Name ........................................................................................................... 246
Open ........................................................................................................... 246
Parent ........................................................................................................... 246
........................................................................................................... 246
QualifiedName
Remove........................................................................................................... 247
........................................................................................................... 247
WSDLFile
11.3 Enumerations................................................................................................................. 248
11.3.1 ENUMCodeGenErrorLevel
................................................................................................... 249
11.3.2 ENUMDOMType
................................................................................................... 250
11.3.3 ENUMLibType
................................................................................................... 251
11.3.4 ENUMProgrammingLanguage
................................................................................................... 252
11.3.5 ENUMProjectItemType
................................................................................................... 253
11.3.6 ENUMProjectType
................................................................................................... 254
11.3.7 ENUMViewMode
................................................................................................... 255
12
MapForceControl
258
259
12.1 Integration at.................................................................................................................
the Application Level
12.1.1 Example: HTML
................................................................................................... 260
...........................................................................................................
260
Instantiate
the Control
...........................................................................................................
260
Add Button
to Open Default Document
...........................................................................................................
260
Add Buttons for Code Generation
261
Connect...........................................................................................................
to Custom Events
263
12.2 Integration at.................................................................................................................
Document Level
12.2.1 Use MapForceControl
................................................................................................... 264
Altova MapForce 2008
7
12.2.2
12.2.3
12.2.4
12.2.5
Use MapForceControlDocument
................................................................................................... 265
Use MapForceControlPlaceHolder
................................................................................................... 266
Query MapForce
...................................................................................................
Commands
267
Examples ................................................................................................... 268
........................................................................................................... 268
C#
.......................................................................................................................... 268
Introduction
..........................................................................................................................
268
Placing
the MapForceControl
..........................................................................................................................
269
Adding
the Placeholder Controls
..........................................................................................................................
271
Retrieving
Command Information
..........................................................................................................................
273
Handling
Events
..........................................................................................................................
274
Testing
the Example
HTML ........................................................................................................... 276
..........................................................................................................................
276
Instantiate
the MapForceControl
..........................................................................................................................
276
Create
Editor window
..........................................................................................................................
276
Create
Project Window
..........................................................................................................................
277
Create
Placeholder for MapForce Helper Windows
..........................................................................................................................
277
Create
a Custom Toolbar
..........................................................................................................................
278
Create
More Buttons
..........................................................................................................................
279
Create
Event Handler to Update Button Status
........................................................................................................... 279
Visual Basic
................................................................................................................. 280
12.3 Command Table
12.3.1 File Menu ................................................................................................... 281
12.3.2 Edit Menu ................................................................................................... 282
12.3.3 Insert Menu ................................................................................................... 283
12.3.4 Project Menu................................................................................................... 284
12.3.5 Component Menu
................................................................................................... 285
12.3.6 Connection Menu
................................................................................................... 286
12.3.7 Function Menu
................................................................................................... 287
12.3.8 Output Menu................................................................................................... 288
12.3.9 View Menu ................................................................................................... 289
12.3.10 Tools Menu ................................................................................................... 290
12.3.11 Window Menu
................................................................................................... 291
12.3.12 Help Menu ................................................................................................... 292
12.3.13 Commands not
...................................................................................................
in Main Menu
293
.................................................................................................................
294
12.4 Accessing MapForce
API
12.5 Object Reference
................................................................................................................. 295
12.5.1 MapForceCommand
................................................................................................... 296
........................................................................................................... 296
Accelerator
........................................................................................................... 296
ID
........................................................................................................... 296
IsSeparator
Label ........................................................................................................... 296
........................................................................................................... 297
StatusText
........................................................................................................... 297
SubCommands
ToolTip........................................................................................................... 297
8
Altova MapForce 2008
12.5.2
12.5.3
MapForceCommands
................................................................................................... 298
Count ........................................................................................................... 298
Item ........................................................................................................... 298
MapForceControl
................................................................................................... 299
...........................................................................................................
299
Properties
.......................................................................................................................... 299
Appearance
.......................................................................................................................... 300
Application
.......................................................................................................................... 300
BorderStyle
.......................................................................................................................... 300
CommandsList
..........................................................................................................................
300
CommandsStructure
(deprecated)
.......................................................................................................................... 301
EnableUserPrompts
.......................................................................................................................... 301
IntegrationLevel
.......................................................................................................................... 301
MainMenu
.......................................................................................................................... 302
ReadOnly
.......................................................................................................................... 302
Toolbars
Methods........................................................................................................... 302
.......................................................................................................................... 302
Exec
.......................................................................................................................... 302
Open
.......................................................................................................................... 303
QueryStatus
Events ........................................................................................................... 303
.......................................................................................................................... 303
OnCloseEditingWindow
.......................................................................................................................... 303
OnContextChanged
.......................................................................................................................... 304
OnDocumentOpened
.......................................................................................................................... 304
OnFileChangedAlert
.......................................................................................................................... 304
OnLicenseProblem
.......................................................................................................................... 304
OnOpenedOrFocused
.......................................................................................................................... 305
OnProjectOpened
.......................................................................................................................... 305
OnUpdateCmdUI
12.5.4
MapForceControlDocument
................................................................................................... 306
........................................................................................................... 306
Properties
.......................................................................................................................... 306
Appearance
.......................................................................................................................... 307
BorderStyle
.......................................................................................................................... 307
Document
.......................................................................................................................... 307
IsModified
.......................................................................................................................... 307
Path
.......................................................................................................................... 307
ReadOnly
.......................................................................................................................... 308
ZoomLevel
Methods........................................................................................................... 308
.......................................................................................................................... 308
Exec
.......................................................................................................................... 308
New
..........................................................................................................................
308
NewDocument
(deprecated)
..........................................................................................................................
309
Open
..........................................................................................................................
309
OpenDocument (deprecated)
..........................................................................................................................
309
QueryStatus
..........................................................................................................................
309
Reload
..........................................................................................................................
310
Save
..........................................................................................................................
310
SaveAs
..........................................................................................................................
310
SaveDocument (deprecated)
Events ........................................................................................................... 310
.......................................................................................................................... 310
OnActivate
Altova MapForce 2008
9
.......................................................................................................................... 310
OnClosed
.......................................................................................................................... 311
OnContextChanged
..........................................................................................................................
311
OnDocumentClosed
(deprecated)
..........................................................................................................................
311
OnDocumentOpened
(deprecated)
.......................................................................................................................... 311
OnDocumentSaveAs
.......................................................................................................................... 312
OnFileChangedAlert
.......................................................................................................................... 312
OnModifiedFlagChanged
.......................................................................................................................... 312
OnOpened
.......................................................................................................................... 312
OnSetEditorTitle
12.5.5
MapForceControlPlaceHolder
................................................................................................... 313
........................................................................................................... 313
Properties
.......................................................................................................................... 313
Label
.......................................................................................................................... 313
PlaceholderWindowID
.......................................................................................................................... 313
Project
Methods........................................................................................................... 314
.......................................................................................................................... 314
OpenProject
Events ........................................................................................................... 314
.......................................................................................................................... 314
OnModifiedFlagChanged
.......................................................................................................................... 314
OnSetLabel
12.5.6
13
Enumerations
................................................................................................... 315
........................................................................................................... 315
ICActiveXIntegrationLevel
........................................................................................................... 315
MapForceControlPlaceholderWindow
Appendices
318
................................................................................................................. 319
13.1 Engine information
13.1.1 XSLT 1.0 Engine:
...................................................................................................
Implementation Information
320
13.1.2 XSLT 2.0 Engine:
...................................................................................................
Implementation Information
322
322
General...........................................................................................................
Information
...........................................................................................................
324
XSLT 2.0
Elements and Functions
13.2 Technical Data
................................................................................................................. 325
13.2.1 OS and Memory
...................................................................................................
Requirements
326
13.2.2 Altova XML...................................................................................................
Parser
327
13.2.3 Altova XSLT...................................................................................................
and XQuery Engines
328
13.2.4 Unicode Support
................................................................................................... 329
...........................................................................................................
329
Windows
2000 and Windows XP
...........................................................................................................
330
Right-to-Left Writing Systems
13.2.5 Internet Usage
................................................................................................... 331
................................................................................................................. 332
13.3 License Information
13.3.1 Electronic Software
...................................................................................................
Distribution
333
13.3.2 Software Activation
and License Metering
...................................................................................................
334
13.3.3 Intellectual Property
...................................................................................................
Rights
335
13.3.4 Altova End User
...................................................................................................
License Agreement
336
10
Altova MapForce 2008
Index
Altova MapForce 2008
11
Chapter 1
MapForce 2008
MapForce 2008
1
3
MapForce 2008
MapForce® 2008 Standard Edition is a visual data mapping tool for advanced data integration
projects.
MapForce® supports:

Graphical mapping from and to any combination and any number of:
- XML Schemas as source and target

Professional Edition, additionally:
- Flat files: delimited (CSV) and fixed-length formats as source and target
- Relational databases as source and target
Enterprise Edition, additionally:
- EDI files: UN/EDIFACT and ANSI X12 as source and target
- FlexText™ files as source and target
- Office Open XML Excel 2007 files as source and target

Automatic code generation
- XSLT 1.0 and 2.0
Professional Edition and Enterprise Edition, additionally:
- XQuery
- Java, C# and C++








On-the-fly transformation and preview of all mappings, without code generation or
compilation
Powerful visual function builder for creating user-defined functions
Accessing MapForce user interface and functions through MapForce API (ActiveX
control)
Definition of custom XSLT 1.0 and 2.0 libraries and integration of custom C++, Java
and C# functions
Support for XPath 2.0 functions in XSLT 2.0 and XQuery
Definition of user-defined functions/components, having complex in/outputs
Support for source-driven / mixed content mapping and copy-all connections
Automatic retention of mapping connectors of missing nodes/items
Professional Edition, additionally:
 XML data mapping to/from databases - IBM DB2 and others
 Direct querying of databases
 SQL-WHERE filter and SQL statement wizard
 SQL SELECT statements as mapping data sources
 Project management functions to group mappings
 MapForce plug-in for Eclipse
 MapForce for Microsoft Visual Studio
Enterprise Edition, additionally:
 Creation of SOAP 1.1 and SOAP 1.2 Web service projects and mapping of Web
service operations from WSDL Files
 Direct calling of Web service functions
 FlexText™: advanced legacy file processing
All transformations are available in one workspace where multiple sources and multiple targets
can be mixed, and a rich and extensible function library provides support for any kind of data
manipulation.
© 2008 Altova GmbH
Altova MapForce 2008
4
MapForce 2008
What is mapping?
Basically the contents of one component are mapped, or transformed, to another component.
An XML, or text documentcan be mapped to a different target XML document. The
transformation is accomplished by an automatically generated XSLT 1.0 or 2.0 Stylesheet.
When creating an XSLT transformation, a source schema is mapped to a target schema.
Thus elements/attributes in the source schema are "connected" to other elements/attributes in
the target schema. As an XML document instance is associated to, and defined by, a schema
file, you actually end up mapping two XML documents to each other.
Altova MapForce 2008
© 2008 Altova GmbH
Chapter 2
What's new in MapForce Version 2008 R2
6
What's new in MapForce Version 2008 R2
2
What's new in MapForce Version 2008 R2
New features in MapForce Version 2008 Release 2 include:



Ability to automatically generate XML Schemas for XML files
Support for Altova Global Resources
Performance optimizations
Altova MapForce 2008
© 2008 Altova GmbH
What's new in MapForce Version 2008 R2
2.1
What's new in MapForce Version 2008
7
What's new in MapForce Version 2008
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
© 2008 Altova GmbH
Altova MapForce 2008
8
What's new in MapForce Version 2008 R2
What's new in MapForce Version 2007 R3
2.2
What's new in MapForce Version 2007 R3
New features in MapForce Version 2007 Release 3 include:


Code generator optimization and improved documentation
Altova MapForce 2008
© 2008 Altova GmbH
Chapter 3
MapForce overview
10
MapForce overview
3
MapForce overview
MapForce has four main areas: the Library pane at left, the Mapping tab group at right, as well
as the Overview and Messages panes below. The actual mapping process is achieved by
manipulating the on-screen graphical elements in the mapping window.

The Libraries pane displays language specific and user defined libraries, as well as the
individual library functions. Functions can be directly dragged into the Mapping tab. The
Add/Remove Libraries... button allows you to import external libraries.

The Mapping tab displays the graphical elements used to create the mapping
(transformation) between the two schemas. The source schema is the "mf-ExpReport"
component window displaying the source schema tree. The target schema is the "
ExpReport-Target" window displaying the target schema tree. Connectors connect
the input and output icons of each schema item. Schema items can be either elements
or attributes.
The XSLT, XSLT2 tabs display a preview of the transformation depending on the
specific language selected.
The Output tab displays a preview of the transformed, or mapped data, in a text view.

The Overview pane displays the mapping area as a red rectangle, which you can drag
to navigate your Mapping.

The Messages pane displays any validation warnings or error messages that might
occur during the mapping process. Clicking a message in this pane, highlights it in the
Mapping tab for you to correct.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce overview
11
© 2008 Altova GmbH
Altova MapForce 2008
12
MapForce overview
3.1
Terminology
Terminology
Library
A Library is a collection of functions visible in the Libraries window. There are several types of
functions, core and language specific, as well as user-defined and custom functions. Please
see the section on functions for more details.
Component
In MapForce a component is a very generic "object". Almost all graphical elements you can
insert/import or place in the Mapping tab, become components.
Components are recognizable by the small triangles they possess. These triangles (input and
output icons) allow you to map data by creating a connection between them.
The following graphical elements are all components:



All schema types: Source and target schemas
All function types: XSLT/XSLT2, as well as Constants, Filters and Conditions
Function
A function is basically an operation on data e.g. Concat. Functions have input and/or output
parameters, where each parameter has its own input/output icon. Functions are available in the
Libraries window, and are logically grouped. Dragging a function into the Mapping window
creates a function component. Please see the section Functions and Libraries for more details.
Item
An item is the unit of data that can be mapped from component to component. An item can be
either an element, an attribute
Each item has an input and output icon which allows you to map data from one item to
another. It is not mandatory that items be of the same type (element or attribute) when you
create a mapping between them.
"Missing" item:
If items have been deleted from one of the components, e.g. a schema element/attribute is
deleted from an XML schema, MapForce automatically creates placeholder items and retains
the previous connectors.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce overview
Terminology
13
Input, Output icon
The small triangles visible on components are input and output icons. Clicking an icon and
dragging, creates a connector which connects to another icon when you "drop" it there. The
connector represents a mapping between the two sets of data the icons represent. Please see
the section "Mapping between components" for more information.
Connector
The connector is the line that joins two icons. It represents the mapping between the two sets
of data the icons represent. Please see the section "Mapping between components" for more
information.
Several types of connector can be defined:
 Target Driven (Standard) connectors, see: "source-driven / mixed content vs. standard
mapping"
 Copy-all connectors, please see "Copy-all connections"
 Source Driven (mixed content) connectors, see "source driven and mixed content
mapping"
Constant
A constant is a component that supplies fixed data to an input icon. The data is entered into a
dialog box when creating, or double clicking, the component. There is only one output icon on a
constant function. You can select from the following types of data: Number, and All other
(String).
Filter: Node/Row
A filter is a component that uses two input and output parameters: node/row and bool, and
on-true, on-false. If the Boolean is true, then the value/content of the node/row parameter is
forwarded to the on-true parameter.
The on-false output parameter, outputs the complement node set defined by the mapping,
please see Multiple target schemas / documents for more information.
Value-Map
The Value-Map component allows you to transform a set of input data, into a different set of
output data, using a type of lookup table. Double clicking the component, opens the value map
table. The left column of the table defines the input, while the right column defines the
transformed data you want to output.
IF-Else Condition
A condition is a component which allows you to pass on different sets of data depending on the
outcome of a preset condition. The component header displays the text if-else. Please see
Condition, in the Reference section for an example.
© 2008 Altova GmbH
Altova MapForce 2008
14
MapForce overview




Terminology
The first input parameter is a bool, which contains the data you are checking against.
The value-true input parameter supplies the data to be passed on, as a result, if the
condition is true.
The value-false supplies the data to be passed on if the condition is false.
The result parameter outputs the data supplied by the value-true/false input
parameters.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce overview
3.2
MapForce components
15
MapForce components
When creating a mapping, single, or multiple data sources, can be mapped to multiple target
components.

Data sources can be: XML-Schemas/documents

Target components can be: XML-Schemas/documents

Target components have their own individual encoding settings. Double click the target
component to see or change these settings. Please see Component for more
information.
The mapping process allows the source data to be selectively transformed (or manipulated
using functions) before it is output, or made available in the Output preview window.
A data source component can have an XML-Schemas/document
To create a schema component (source):
1. Click the Insert | XML Schema/File icon
.
2. Select the schema file you want to use, from the "Open", dialog box.
A further dialog box appears prompting you to select an XML sample file, if you intend
to use this schema as a data source in this mapping.
3. Click Browse... if this is the case, and select the XML instance file.
The schema component now appears in the Mapping tab.
You can now connect the schema source output icons, with the target (or function)
input icons, to create your mappings.
To create a schema component (target)
1. Click the Insert | XML Schema/File icon
.
2. Select the schema file you want to use from the "Open", dialog box.
Select Skip when you are prompted to supply an XML sample file.
3. Select the Root element of the schema you want to use (Company) and click OK.
© 2008 Altova GmbH
Altova MapForce 2008
16
MapForce overview
MapForce components
The schema (snippet) with the root element appears as a schema component.
The target schema is the basis of the XML document you want to have generated by the
transformation.
The target schema/document can, of course, differ dramatically from the source schema. This
is where the mapping process comes in, you can map any item in the source schema to any
other item (element/attribute), in the target schema. The source data then appears at the
position defined by your mapping, in the target document.
You can also define multiple output schemas. MapForce then generates XSLT for each target
schema. You can then selectively preview the different output schemas in the Output preview
window.
Please note:
It is not necessary to associate an XML Instance document to a target schema. If you
do so, then the XML instance document is ignored and does not affect the
transformation in any way.
Clicking the root element of a schema and hitting the * key on the numeric keypad,
expands all the schema items!
Schema component context menu
Right clicking a schema component in the Mapping window opens the context menu.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce overview
MapForce components
17
Align tree left
Aligns all the items along the left hand window border. This display is useful when creating
mappings from the source schema.
Align tree right
Aligns all the items along the right hand window border. This display is useful when creating
mappings to the target schema.
Cut/Copy/Paste/Delete
The standard MS Windows Edit commands, allow you to cut, copy etc., any components or
functions visible in the mapping window. All connectors will be retained except for those which
would have to be replaced.
Change Root element
Allows you to change the root element of the XML instance document. Useful in the target
schema window, as this limits or preselects the schema data.
Edit Schema definition in XMLSpy.
Starts XMLSpy and opens the schema file, ready for you to edit.
Component Settings
Opens the Component Settings dialog box.
Allows you to select the input and/or output XML Instance. Please see Component Settings for
more information on these settings.
Item Context menu
Right clicking an item in a component, opens a context menu with options enabled for the
specific type of component.
Duplicate input
Inserts a copy/clone of the selected item, allowing you to map multiple input data to this item.
Duplicate items do not have output icons, you cannot use them as data sources. Please see
the Duplicating input items section in the tutorial for an example of this.
Please note:
Complex parameters of inlined user-defined functions/structures cannot be duplicated.
Please see "Complex user-defined function - XML node as input" for more information.
Remove duplicate
Removes a previously defined duplicate item. Please see the Duplicating input items section in
the tutorial for more information.
Delete connections
Allows you to delete connections related to that specific item: all direct connections, all
incoming, or outgoing, child connections.
Component
Opens the Component Settings dialog box for the specific component.
© 2008 Altova GmbH
Altova MapForce 2008
18
MapForce overview
3.3
Functions and libraries
Functions and libraries
The Libraries pane displays the available libraries for the currently selected programming
language, as well as the individual functions of each library. Functions can be directly dragged
into the Mapping tab. Once you do this, they become function components.
The standard core and xslt libraries are always loaded when you start MapForce, and do not
need to be added by the user. The Core library is a collection of functions that can be used to
produce all types of output: XSLT. The other libraries (XSLT, XSLT2, XPath2, Lang etc.)
contain functions associated with each separate type of output.
Selecting:
XSLT, enables the core and XSLT functions (XPath 1.0 and XSLT 1.0 functions).
XSLT2, enables the core, XPath 2.0, and XSLT 2.0 functions.
XPath 2.0 restrictions:
Several XPath 2.0 functions dealing with sequences are currently not available.
To use a function in Mapping window:
1. First select the programming language you intend to generate code for, by clicking
one of the output icons in the title bar: XSLT/XSLT2.
The functions associated with that language are now visible in the Libraries window.
The expand and contract icons show, or hide the functions of that library.
2. Click the function name and drag it into the Mapping window.
3. Use drag and drop to connect the input and output parameters to the various icons.
Note that placing the mouse pointer over the "result = xxx" expression in the library
pane, displays a ToolTip describing the function in greater detail.
Function tooltips:
Explanatory text (visible in the libraries pane) on individual functions, can be toggled on/off by
clicking the "Show tips" icon
in the title bar. Placing the mouse pointer over a function
header, displays the information on that function.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce overview
Functions and libraries
19
To add new function libraries:
MapForce allows you to create and integrate your own function libraries, please see the
sections: Adding custom XSLT 1.0 functions, Adding custom XSLT 2.0 functions and
User-defined functions for more information.
Please note:
custom functions/libraries can be defined for XSLT and XSLT 2.
Extendable functions
Several functions available in the function libraries are extendable: for e.g. the concat,
"logical-and", "logical-or" functions. The parameters of these types of function can be
inserted/appended and deleted at will. Clicking the "plus" icon inserts or appends the same type
of parameter, while clicking the check mark deletes the parameter.
Please note: "dropping" a connector on the "plus" symbol, automatically inserts/appends the
parameter and connects it.
© 2008 Altova GmbH
Altova MapForce 2008
20
MapForce overview
3.3.1
Function context menu
Functions and libraries
Function context menu:
Right clicking a function in the Mapping window, opens the context window.
Edit Constant
Allows you to change the entry currently defined in the Constant component. A Constant is
added by clicking the Insert Constant icon
.
Priority Context
When applying a function to different items in a schema, MapForce needs to know what the
context node will be. All other items are then processed relative to this one.
This is achieved by designating the item (or node) as the priority context. A circle appears
around the icon so designated. Please see Priority Context in the Reference section, for an
example.
Show library in function header
Displays the library name in the function component.
Replace component with internal function structure
Replaces the user-defined component/function with its constituent parts.
Cut/Copy/Paste/Delete
The standard MS Windows Edit commands, allow you to cut, copy etc., any components or
functions visible in the mapping window. All connectors will be retained except for those which
would have to be replaced.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce overview
3.4
Mapping between components
21
Mapping between components
A connector visualizes the mapping between the two sets of data and allows the source data
(value) to appear, or be transformed, into the target schema/document.






Components and functions have small "connection" triangles called: input or output
icons. These icons are positioned to the left and/or right of all "mappable" items.
Clicking an icon and dragging, creates the mapping connector. You can now drop it
on another icon. A link icon appears next to the text cursor when the drop action is
allowed.
Clicking an item name (element/attribute) automatically selects the correct icon for the
dragging action.
An input icon can only have one connector.
If you try and connect a second connector to it, a prompt appears asking if you want to
replace or duplicate the input icon.
An output icon can have several connectors, each to a different input icon.
Positioning the mouse pointer over the straight section of a connector (close to the
input/output icon) highlights it, and causes a popup to appear. The popup displays the
name(s) of the item(s) at the other end of the connector. If multiple connnectors have
been defined from the same output icon, then a maximum of ten item names will be
displayed.
Clicking the straight section of the connector highlights it and allows you to reposition it
by dragging it elsewhere.
Number of connectors
Input and output icons appear on most components, there is not, however, a one to one
relationship between their numbers.






Each schema item (element/attribute) has an input and output icon.
Schema components within user-defined functions only have output icons.
Duplicated items only have input icons. This allows you to map multiple inputs to them.
Please see Duplicating Input items for more information.
Functions can have any number of input and output icons, one for each parameter.
E.g. the Add Function has two (or more) input icons, and one output icon.
Special components, can have any number of icons, e.g. the Constant component only
© 2008 Altova GmbH
Altova MapForce 2008
22
MapForce overview
Mapping between components
has an output icon.
This example shows how you can use the concat function to combine the First and Last names
and place the result in the Title element. The constant component supplies the space character
between the two names.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce overview
3.4.1
Mapping between components
23
Missing items
Over time, it is likely that the structure of one of the components in a mapping may change e.g.
elements or attributes are added/deleted to an XML schema. MapForce uses placeholder items
to retain all the connectors, and any relevant connection data between components, when items
have been deleted.
Example:
Using the MFCompany.xsd schema file as an example. The schema is renamed to
MyCompany.xsd and a connector is created between the Company item in both schemas. This
creates connectors for all child items between the components, if the Autoconnect Matching
Children is active.
While editing MyCompany.xsd, in XMLSpy, the First and Last items in the schema are deleted.
Returning to MapForce opens a Changed Files notification dialog box, prompting you to reload
the schema. Clicking Reload updates the components in MapForce.
The deleted items and their connectors are now marked in the MyCompany component. You
could now reconnect the connectors to other items if necessary, or delete the connectors.
Note that you can still preview the mapping (or generate code), but warnings will appear in the
Messages window if you do so at this point. All connections to, and from, missing items are
ignored during preview or code-generation.
Clicking one of the highlighted connectors and deleting it, removes the "missing" item from the
component, e.g. Last, in MyCompany.
© 2008 Altova GmbH
Altova MapForce 2008
24
MapForce overview
Mapping between components
Renamed items:
If a parent item is renamed e.g. Person to ZPerson, then the original parent item connector is
retained and the child items and their connectors are deleted.
"Copy all" connectors and missing items:
Copy all connections are treated in the same way as normal connections, with the only
difference being that the connectors to the missing child items are not retained or displayed.
Renamed or deleted component sources:
If the data source of a component i.e. schema has been renamed or deleted, then all items it
contained are highlighted. The red frame around the component denotes that there is no valid
connection to a schema and prevents preview and code generation.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce overview
Mapping between components
25
Placing the mouse cursor over the highlighted component, opens a popup containing pertinent
information.
Double clicking the title bar of the highlighted component opens the Component Settings dialog
box. Clicking the Browse button in the Schema file group allows you to select a different, or
backed-up version of the schema. Please see "Component" in the Reference section for more
information.
© 2008 Altova GmbH
Altova MapForce 2008
26
MapForce overview
Mapping between components
All valid/correct connections will be retained if you select a schema of the same structure.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce overview
3.5
Validating mappings and mapping output
27
Validating mappings and mapping output
Connectors and validation
It is not mandatory for functions or components to be mapped. The Mapping tab is a work area
where you can place any available components. XSLT 1.0, XSLT 2 is only generated for those
components for which valid connections exist.
To validate your mapping:



Click the Validate Mapping icon
, or select the menu item File | Validate
Mapping.
Click one of the preview tabs, (XSLT, XSLT 2.0, or Output), or
Select the menu option File | Generate XSLT/XSLT2
A validation message appears in the Messages window.
Note that you can use multiple message tabs if you project contains many separate
mapping files. Click one of the numbered tabs in the Messages window, and click the
preview tab for a different mapping in your project. The validation message now
appears in the tab that you selected. The original message in tab 1, is retained
however.
Use the different icons of the Messages tab to:
 Filter the message types, errors or warnings
 Scroll through the entries
 Copy message text to the clipboard
 Find a specific string in a message
 Clear the message window.
Validation messages:

Validation successful - X Error(s), Y Warning(s).
Warnings, alert you to something, while still enabling the mapping process and preview of the
transformation result to continue. It is therefore possible for a mapping to have 0 errors and Y
warnings.
Errors, halt the transformation process and deliver an error message. An XSLT, XQuery, or
Output preview is not possible when an error of this type exists. Clicking a validation message
in the Messages window, highlights the offending component icon in the Mapping window.
Component connections and validation results:
Free standing components
 Do not generate any type of error or warning message.
Partially connected components can generate two types of warning:

If a function component input icon is unconnected, an error message is generated and
the transformation is halted.
© 2008 Altova GmbH
Altova MapForce 2008
28
MapForce overview

Validating mappings and mapping output
If the function output icon is unconnected, then a warning is generated and the
transformation process continues. The offending component and its data are ignored,
and are not mapped to the target document.
Validating mapped OUTPUT:
Clicking the Output tab uses the MapForce, XSLT 1.0/2.0 or XQuery engine, to transform the
data and produce a result in a Text view. If the data is mapped to an XML Schema, then the
resulting XML document can be validated against the underlying schema.

Click the Validate button
to validate the document against the schema. A "Output
XML document is valid" message, or a message detailing any errors appears.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce overview
3.6
XSLT, Output tab - generating XSLT
29
XSLT, Output tab - generating XSLT
The XSLT, XSLT2, and Output tabs of the Mapping tab group, supply a preview of the
generated XSLT and of the resulting transformation using the XML instance file.
To save the generated XSLT code:
1. Select the menu option File | Generate code in | XSLT 1.0 (or XSLT 2.0).
2. Browse for the folder where you want to save the XSLT file.
3. A message appears when the generation was successful.
4. Navigate to the previously defined folder, where you will find the generated XSLT file.
To save the XML data visible in the Output tab.
1. Click the Output tab to preview the mapping result.
2. Click the "Save generated output" icon
be saved.
, and specify where you want the result to
To transform an XML/Schema file using the generated XSLT:
1. Open the XML file in the editor of your choice (XMLSpy for example).
2. Assign the XSLT file to the XML file (XSL/XQuery | Assign XSL)
3. Start the transformation process (XSL/XQuery | XSL Transformation)
The transformed XML document appears in your editor.
Please note:
Opening a mapping that contains features available in a higher-level MapForce edition is not
possible.
E.g. A mapping containing Web service features in the Professional version, or database
mappings the Standard editions is not possible.
© 2008 Altova GmbH
Altova MapForce 2008
30
MapForce overview
3.7
Loops, groups and hierarchies
Loops, groups and hierarchies
There are several ways of looping through source and target hierarchies which allow you to
define how you want to loop, or group, sets of data.
The following links show you how this can be achieved. Please note that these examples are
not sequential, they appear in various locations within the documenation.
Value-Map - lookup table
Priority Context
Altova MapForce 2008
© 2008 Altova GmbH
Chapter 4
MapForce tutorial
32
MapForce tutorial
4
MapForce tutorial
Tutorial example:
In the tutorial, a simple employee travel expense report will be mapped to a more complex
company report.
Each employee fills in the fields of the personal report. This report is mapped to the company
report and routed to the Administration department. Extra data now has to be entered in
conjunction with the employee, the result being a standardized company expense report.
Further formatting, cost summation, and conditional viewing options of the expense report, are
made possible by having the target XML document associated with a StyleVision Power
Stylesheet designed in StyleVision.
Aim of the tutorial:
 To transform the personal expense report to a company expense travel report
 Selectively filter the source data and only let the travel expense records through
 Generate an XSLT transformation file
 Transform the personal expense report to the company expense report using the
generated XSLT file
 Assign a StyleVision Power Stylesheet to the resulting XML file, enabling you to view
and edit the resulting file in the Authentic View
The tutorial makes use of the following components:
 source and (multiple) target schemas
 several functions including: concat, filter, equal and constants
Files used in the tutorial:
All the files used in this tutorial are available in the C:\Documents and
Settings\<username>\My Documents\Altova\MapForce2008\MapForceExamples\Tutorial\
folder. The XSLT and transformed XML files are also supplied.
If multiple users use the same PC, and a different user logs on, a message box opens and
prompts the new user if the installer should add the necessary files for that user. If yes, then
the example files for that user are placed in the ...\User folder\My Documents\Altova\
MapForce2008\MapForceExamples\Tutorial.
Tutorial files:
Personal expense report
Tut-ExpReport.mfd
The expense report mapping (single target)
Tut-ExpReport-multi.mf The multi-schema target expense report mapping
d
mf-ExpReport.xml
mf-ExpReport.xsd
mf-ExpReport.sps
Personal expense report XML instance document
Associated schema file
StyleVision Power Stylesheet used to view the personal expense
report in Authentic View of XMLSpy, or Authentic Desktop.
Company expense report
ExpReport-Target.xml Company expense report XML instance document
ExpReport-Target.xsd Associated schema file
ExpReport-Target.sps StyleVision Power Stylesheet used to view the Company expense
report in Authentic View of XMLSpy, or Authentic Desktop.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce tutorial
© 2008 Altova GmbH
33
Altova MapForce 2008
34
MapForce tutorial
4.1
Setting up the mapping environment
Setting up the mapping environment
This section deals with defining the source and target schemas we want to use for the mapping.

Start MapForce.
Creating the source schema component:
1. Click the Insert XML Schema/File
icon.
2. Select the mf-ExpReport.xsd file from the Open dialog box.
You are now prompted for a sample XML file to provide the data for the preview tab.
3. Click the Browse... button, and select the mf-ExpReport.xml file.
The source schema component now appears in the Mapping tab.
4. Click the expense-report entry and hit the * key, on the numeric keypad, to view all the
items.
5. Click the expand icon at the lower right of the component window, and resize the
window.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce tutorial
Setting up the mapping environment
35
Please note:
MapForce can automatically generate an XML schema based on an existing XML file,
if the XML Schema is not available. A dialog box automatically appears, prompting you
if an accompanying XML Schema file cannot be found.
Creating the target schema component:
1. Click the Insert XML Schema/File icon.
2. Select the ExpReport-Target.xsd file from the Open dialog box.
You are now prompted for a sample XML file for this schema.
3. Click the Skip button, and select Company as the root element of the target document.
The target schema component now appears in the mapping tab.
4. Click the Company entry and hit the * key on the numeric keypad to view all the items.
5. Click the expand window icon and resize the window.
We are now ready to start mapping schema items from the source to the target
© 2008 Altova GmbH
Altova MapForce 2008
36
MapForce tutorial
Setting up the mapping environment
schema.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce tutorial
4.2
Mapping schema items
37
Mapping schema items
This section deals with defining the mappings between the source and target schema items.
1. Click the expense-report item in the source schema and drag.
A connector line is automatically created from the output icon and is linked to the
mouse pointer which has now changed shape.
2. Move the mouse pointer near to the Company item in the target schema, and "drop"
the connector the moment the mouse pointer changes back to the arrow shape. A
small link icon appears below the mouse pointer, and the input icon is highlighted when
the drop action will be successful.
A connector has now been placed between the source and target schemas. A mapping
has now been created from the schema source to the target document.
3. Use the above method to create a mapping between the Person and Employee items.
Auto-mapping
MapForce allows you to automatically connect child elements of the same name in both
schemas. For more information please see the section on Connector properties.
1. Right click the "Person" connector and select "Connect matching children" from the
pop-up menu.
If the child items are automatically connected, auto connect child items is active.
© 2008 Altova GmbH
Altova MapForce 2008
38
MapForce tutorial
Mapping schema items
This opens the Connect Matching Children dialog box.
2. Activate all four check boxes, and click OK.
Mappings have been automatically created for the Title and Email items of both
schemas.
3. Click the Output tab to see if there is a result.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce tutorial
Mapping schema items
39
You will notice that the Title and Email fields contain data originating from the XML
Instance document.
4. Click the Mapping tab to continue mapping.
Please note:
The settings you select in the Connect Matching Children dialog box, are retained until
you change them. These settings can be applied to a connection by either: using the
context menu, or by clicking the Auto connect child items icon to activate, or deactivate
this option.
© 2008 Altova GmbH
Altova MapForce 2008
40
MapForce tutorial
4.3
Using functions to map data
Using functions to map data
The aim of this section is to combine two sets of data from the source schema, and place the
result in a single item in the target document. Please note, that some of the previously defined
mappings are not shown in the following screen shots for the sake of clarity.
This will be done by:
 Using the Concat string function to combine the First and Last elements of the source
schema
 Using a Constant function to supply the space character needed to separate both
items
 Placing the result of this process into the Name item of the target schema.
Using functions to combine items:
1. Click the concat entry of the string functions group, in the Core library, and drag it into
the Mapping tab
.
2. Create a connection between item First and value1 of the concat component.
3. Click the Insert Constant icon
Altova MapForce 2008
in the icon bar, to insert a constant component.
© 2008 Altova GmbH
MapForce tutorial
Using functions to map data
41
4. Enter a space character in the text box and click OK.
The constant component is now in the working area. Its contents are displayed next to
the output icon.
5. Create a connection between the constant component and value2 of the concat
component.
6. Click the item Last and drop the connector on the "+" icon of the concat function, just
below value2. The mouse cursor changes to show when you can drop the connector.
This automatically enlarges the concat function by one more item (value), to which the
Last item is connected.
© 2008 Altova GmbH
Altova MapForce 2008
42
MapForce tutorial
Using functions to map data
7. Connect the result icon of the concat component, to the Name item in the target
schema.
8. Click the Output tab to see the result of the current mapping.
You will see that the Person name "Fred Landis" is now contained between the Name
tags. The first and last name have been separated by a space character as well.
Mapping the rest of the personal data:
1. Create mappings between the following items:
 currency to Currency
 Phone to Tel.
 expto to Bill-to
 Date to Date
2. Click the Output tab to see the result.
There are currently five items originating from the assigned XML instance file.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce tutorial
Using functions to map data
43
Please note:
Functions can be grouped into user-defined functions/components to maximize screen space.
Please see the section on "User-defined functions/components" for an example on how to
combine the concat and constant functions into a single user-defined function/component.
© 2008 Altova GmbH
Altova MapForce 2008
44
MapForce tutorial
4.4
Filtering data
Filtering data
The aim of this section is to filter out the Lodging and Meal expenses, and only pass on the
Travel expenses to the target schema/document.
This will be done by:
 Using the Equal function to test the value of a source item
 Using a Constant function to supply the comparison string that is to be tested
 Using the Filter function which passes on the Travel data, if the bool input value is true
 Placing the on-true result of this process, into the expense-item element of the target
schema/document.
Filtering data:
1. Insert a constant component and enter the string Travel in the input field.
2. Insert the logical function equal from the core library (logical functions group).
3. Connect the (expense-item) type item in the source schema, to the a parameter of the
equal function.
4. Connect the result icon of the constant component, to the b parameter of the equal
function.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce tutorial
Filtering data
45
5. Select the menu option Insert | Filter for Nodes/Rows.
6. Connect the result icon of the equal component, to the bool parameter of the filter
component.
7. Connect the expense-item icon of the source schema with the node/row parameter of
the filter component.
Note that the filter component name, now changes to "expense-item".
8. Connect the on-true icon of the filter component with the expense-item element of the
© 2008 Altova GmbH
Altova MapForce 2008
46
MapForce tutorial
Filtering data
target document.
9. Connect the Travel item in the source schema, with the Travel item in the target
schema/document.
10. Connect the Trav-cost item with the Travel-Cost item in the target schema/document.
11. Click the Output tab to see the result.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce tutorial
Filtering data
47
Please note:
The on-false parameter of the filter component, outputs the complement node set that
is mapped by the on-true parameter. In this example it would mean all non-travel
expense items.
The number of expense-items have been reduced to three. Checking against the supplied
mf-ExpReport.xml file, reveals that only the Travel records remain, the Lodging and Meal
records have been filtered out.
© 2008 Altova GmbH
Altova MapForce 2008
48
MapForce tutorial
4.5
Generating XSLT 1.0 and 2.0 code
Generating XSLT 1.0 and 2.0 code
MapForce can generate two flavors of XSLT code:
1. Select the menu item File | Generate code in | XSLT 1.0 (or XSLT 2.0).
2. Select the folder you want to place the generated XSLT file in, and click OK.
A message appears showing that the generation was successful.
3. Navigate to the designated folder and you will find the XSLT with the file name
MappingMapToExpReport-Target.xslt
To transform the personal expense report to the company expense report:
Having installed either XMLSpy, or Authentic Desktop you can easily transform the source to
the target document.
1. Start XMLSpy, or Authentic Desktop and open the supplied mf-ExpReport.xml
document.
2. Select the menu option Tools | Options and click the XSL tab.
3. Enter .xml in the Default file extension of output file field, and click OK.
4. Select the menu option XSL/XQuery | XSL Transformation.
5. Select the previously generated MapToExpReport-Target.xslt file, and click OK.
An XSL Output.xml file is created.
XMLSpy automatically selects the correct XSLT engine for the transformation.
6. Select the menu option Authentic | Assign a StyleVision Power Stylesheet.
7. Select the supplied stylesheet ExpReport-Target.sps and click OK.
8. Click the Authentic tab to switch to the Authentic view.
9. Click the add Expense-detail text in the Detail column.
The field changes to a check box.
10. Click the check box to see the detailed expenses.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce tutorial
Generating XSLT 1.0 and 2.0 code
49
The expense report can now be completed with extra information relating to
Accommodation, Entertainment and Misc. costs if necessary.
Please note:
The Total field automatically sums up all Cost fields of each record. Once a number
exists in all these fields, the Total field becomes live and the NaN (Not a Number) entry
disappears. Subsequent changing of any of the Cost fields, automatically adjusts the
Total field.
© 2008 Altova GmbH
Altova MapForce 2008
50
MapForce tutorial
4.6
Multiple target schemas / documents
Multiple target schemas / documents
This section deals with creating a second target schema / document, into which non-travel
expense records will be placed, and follows on from the current tutorial example
Tut-ExpReport.mfd.
Creating the second target schema component:
1. Click the Insert XML Schema/File icon.
2. Select the ExpReport-Target.xsd file from the Open dialog box.
You are now prompted for a sample XML file for this schema.
3. Click Skip, and select Company as the root element of the target document.
The target schema component now appears in the Mapping tab.
4. Click the Company entry and hit the * key on the numeric keypad to view all the items.
5. Click the expand window icon and resize the component. Place the schema
components so that you can view and work on them easily.
There is now one source schema, mf-expReport, and two target schemas, both
ExpReport-Target, visible in the Mapping tab.
Filtering out the non-travel data:
1. Connect the on-false icon of the filter component with the expense-item element of
the second target schema / document.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce tutorial
Multiple target schemas / documents
51
A message appears stating that you are now working with multiple target schemas /
documents.
2. Click OK to confirm.
An Preview icon is now visible in the title bar of each target schema component.
Clicking the Preview icon defines which of the target schema data is to be displayed,
when you subsequently click the XSLT, XSLT2, XQuery, or Output tabs.
Creating mappings for the rest of the expense report data:
1. Connect the Lodging item in the source schema to Accommodation in the second
target schema.
2. Connect the Lodging item to DomesticAcc.
3. Connect the Lodge-Cost item to DomesicAcc-Cost.
4. Create the following mappings between the source schema and second target schema.
You created the same connectors for the first target schema, so there is nothing new
here:
Source schema - connect:
to... second Target schema
Person
Result of existing First
and Last concatenation
Title
Phone
Email
currency
Employee
© 2008 Altova GmbH
Name
Title
Tel.
Email
Currency
Altova MapForce 2008
52
MapForce tutorial
expto
Date
Altova MapForce 2008
Multiple target schemas / documents
Bill-to
Date
© 2008 Altova GmbH
MapForce tutorial
4.6.1
Multiple target schemas / documents
53
Viewing and generating multiple target schema output
Clicking the Preview icon lets you select which of the schema targets you want to preview.
To view specific XSLT output:
1. Click the Preview icon in the title bar of the second schema component, to make it
active.
2. Click the Output tab of the Mapping tab group.
The XML output contains two records both billed to Sales: the Domestic
Accommodation cost of $121.2 and an Expense-item record which only contains a
date. This record originates from the expense-item Meal. There is currently no mapping
between meal costs and domestic accommodation costs, and even if there were, no
cost would appear as the XML instance does not supply one.
Please note:
You can save this XML data by clicking the Save generated output icon, while viewing
the XML output in the preview window
.
The resulting XML instance file can also be validated against the target schema, by
clicking the validate button
.
To generate XSLT 1.0 / XSLT 2.0 code for multiple target schemas:
1. Select the menu item File | Generate code in | XSLT 1.0 (or XSLT 2.0).
2. Select the folder you want to place the generated XSLT files, and click OK.
A message appears showing that the generation was successful.
3. Navigate to the designated folder and you will find two XSLT files with the file names:
© 2008 Altova GmbH
Altova MapForce 2008
54
MapForce tutorial
Multiple target schemas / documents
MappingExpReport-Target.xslt and MappingExpReport-Target2.xslt
4. Having installed either XMLSpy, or Authentic Desktop, assign either of these two XSLT
files to the mf-ExpReport.xml file, and start the transformation process.
5. Assign the supplied stylesheet, ExpReport-Target.sps to the file, and click the
Authentic tab.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce tutorial
4.7
Mapping multiple source items, to single target items
55
Mapping multiple source items, to single target items
In this section two simple employee travel expense reports will be mapped to a single company
report. This example is a simplified version of the mapping you have already worked through in
the Multiple target schemas / documents section of this tutorial.
Aim of this section:
To merge two personal travel expense reports into a company expense travel report.
Please note that the files used in this example, have been optimized to show how to map data
from two input XML files into a single item in the target schema, this is not meant to be a
real-life example.
Files used in this section:
mf-ExpReport.xml
mf-ExpReport2.xml
mf-ExpReport-combined.xml
ExpReport-combined.xsd
ExpReport-combined.sps
Tut-ExpReport-msource.mfd
Input XML file used in previous section
The second input XML file
The resulting file when the mapping has
been successful
The target schema file into which the two
XML source data will be merged.
The StyleVision Stylesheet used to view
the mapping result in Authentic view.
The mapping file for this example
Please note:
The files used in this section are also available in the C:\Documents and
Settings\<username>\My
Documents\Altova\MapForce2008\MapForceExamples\Tutorial\ folder.
© 2008 Altova GmbH
Altova MapForce 2008
56
MapForce tutorial
4.7.1
Creating the mappings
Mapping multiple source items, to single target items
The method described below, is a recapitulation of how to set up the mapping environment.
1. Click the Insert XML Schema/File icon.
2. Select the mf-ExpReport.xsd file from the Open dialog box, click Browse... and select
the mf-ExpReport.xml file as the XML instance file.
3. Click the expense-report entry, hit the * key on the numeric keypad to view all the
items; resize the component if necessary.
4. Click the Insert XML Schema/File icon.
5. Select the ExpReport-combined.xsd file from the Open dialog box.
You are now prompted for a sample XML file for this schema.
6. Click Skip, and select Company as the root element of the target document.
7.
The target schema component now appears in the mapping tab.
Click the Company entry, hit the * key on the numeric keypad to view all the items, and
resize the window if necessary.
Make sure that the "Auto connect child items" icon
create the following mappings.
is deactivated, before you
Create the following mappings between the two components:
 Expense-report to Company
 Person to Employee
 Last to Name
 Title to Title
 Phone to Tel.
 Email to Email
 expense-item to expense-item
 Travel to Travel and
Altova MapForce 2008
© 2008 Altova GmbH
MapForce tutorial

Mapping multiple source items, to single target items
57
Trav-cost to Travel-Cost.
The mapping is shown below.
8. Click the Output tab to see the result of the current mapping.
Please note:
Empty <expense-item/> tags are generated when child items of a mapped parent item
, exist in the source file, which have not been mapped to the target schema. In this
case, only the travel items of the expense-item parent have been mapped. There are
however, two other expense items in the list: one lodging and one meal expense item.
Each one of these items generates an empty parent expense-item tag.
© 2008 Altova GmbH
Altova MapForce 2008
58
MapForce tutorial
Mapping multiple source items, to single target items
To avoid generating empty tags, create a filter such as the one described previously in
the tutorial, under Filtering data, or connect the Travel item to the expense-item.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce tutorial
4.7.2
Mapping multiple source items, to single target items
59
Duplicating input items
We now need to duplicate the input items of the target component to be able to create
mappings from a different source XML file. To achieve this we will:


add the second XML source file, and
create mappings from it, to the "same" inputs in the target XML file.
Duplicating input items:
1. Right click the Employee entry in the target XML file.
2. Select the menu option Duplicate input.
A second Employee item has now been added to the component, as Employee(2).
3. Click the expand icon to see the items below it.
© 2008 Altova GmbH
Altova MapForce 2008
60
MapForce tutorial
Mapping multiple source items, to single target items
The structure of the new Employee item, is an exact copy of the original, except for the
fact that there are no output icons for the duplicated items.
You can now use these new duplicate items as the target for the second source XML
data file.
Use the same method as before, to insert the second XML instance file:
1. Click the Insert Schema | XML instance icon.
2. Select the mf-ExpReport.xsd file from the Open dialog box, click Browse..., and select
the mf-ExpReport2.xml file as the XML instance file.
3. Click the expense-report entry, hit the * key on the numeric keypad to view all items,
and resize the component if necessary.
For the sake of clarity, the new component has been placed between the two existing
ones in the following graphics.
4. Create the same mappings that were defined for the first XML source file:
Altova MapForce 2008
© 2008 Altova GmbH
MapForce tutorial
Mapping multiple source items, to single target items








61
Person to Employee(2)
Last to Name
Title to Title
Phone to Tel.
Email to Email
expense-item to expense-item
Scroll down, and map Travel to Travel, and
Trav-cost to Travel-Cost.
5. Click the Output tab to see the result of the mapping.
© 2008 Altova GmbH
Altova MapForce 2008
62
MapForce tutorial
Mapping multiple source items, to single target items
The data of the second expense report has been added to the output file. Johnson and
his travel costs have been added to the expense items of Fred Landis in the company
expense report.
To save the generated output to a file:
 Click the Save icon
which appears in the title bar when the Output tab is active.
The file, mf-ExpReport-combined.xml, is available in the C:\Documents and
Settings\<username>\My Documents\Altova\MapForce2008\MapForceExamples\Tutorial\
folder. Please note that it has been assigned an SPS file, which allows you to view the XML file
in Authentic View of Authentic Desktop, or XMLSpy.
To remove duplicated items:
 Right click the duplicate item and select the Remove Duplicate entry from the menu.
To see a further example involving duplicate items, please see the PersonList.mfd sample file
available in the C:\Documents and Settings\<username>\My
Documents\Altova\MapForce2008\MapForceExamples folder.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce tutorial
Mapping multiple source items, to single target items
63
In the example:


Different elements of the source document are mapped to the "same" element in the
target Schema/XML document.
Specific elements (Manager etc.) are mapped to a generic one using a "role" attribute.
© 2008 Altova GmbH
Altova MapForce 2008
Chapter 5
Methods of mapping data (Standard / Mixed / Copy All)
66
Methods of mapping data (Standard / Mixed / Copy All)
5
Methods of mapping data (Standard / Mixed / Copy All)
MapForce supports various methods of mapping data:
Target Driven (Standard)
Standard mapping means the normal method of mapping used in MapForce, i.e. the output
depends on the sequence of the target nodes. Please see Source-driven / mixed content vs.
standard mapping for more information.


Mixed content text node content is not supported/mapped.
The sequence of child nodes is dependent on the target schema file.
Source driven / mixed content mapping
Mixed content mapping enables you to automatically map text and child nodes in the same
sequence that they appear in the XML source file.


Mixed content text node content is supported/mapped.
The sequence of child nodes is dependent on the source XML instance file.
Copy All mapping
This type of connection allow you to organize your workspace and automatically connect all
identical items in source and target components, meaning that, depending on the source and
target type:

all source child items are copied to the target component, if either the source and
target types are identical, or if the target type is xs:anyType

if the source and target types are not identical, and if the target type is not
xs:anyType, the source data is transferred/mapped to the respective target items of the
same name and the same hierarchy level. If the names of the target items differ, then
the target item is not created.
Altova MapForce 2008
© 2008 Altova GmbH
Methods of mapping data (Standard / Mixed / Copy All)
5.1
Source driven / mixed content mapping
67
Source driven / mixed content mapping
MapForce supports source driven / mixed content mapping. Source driven / mixed content
mapping enables you to automatically map text and child nodes in the same sequence that they
appear in the XML source file.
Source-driven mapping can, of course, also be applied to XML schema complexType items if
you wish. Child nodes will then be mapped according to their sequence in the XML source file.
Source driven / mixed content mapping supports:


XML schema complexTypes as source components,
XML schema complexTypes of type mixed content, i.e. mixed=true, as source
components,

XML schema complexTypes (including mixed content), as target components
Please note:
Mixed content text nodes can only be mapped in their entirety; you cannot limit, or
transform the data they contain. Filters, or any other type of function, cannot be used to
access text node data.
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.
Right clicking a connector and selecting Connection settings, allows you to annotate, or label
the connector. Please see section "Connection" in the Reference section for more information.
© 2008 Altova GmbH
Altova MapForce 2008
68
Methods of mapping data (Standard / Mixed / Copy All)
Source driven / mixed content mapping
The files used in the following example (Tut-Orgchart.mfd) are available in the C:\Documents
and Settings\<username>\My
Documents\Altova\MapForce2008\MapForceExamples\Tutorial\ folder.
The image below shows the content model of the Description element (Desc) of the
Tut-OrgChart.xsd schema file. This definition is identical in both the source and target
schemas used in this example.
Content model of para element:




para is a complexType with mixed = true, of type TextType.
bold and italic elements are both of type xsd:string, they have not been defined as
recursive in this example. i.e. neither bold, nor italic are of type "TextType".
bold and italic elements can appear any number of times in any sequence within para.
any number of text nodes can appear within the para element, interspersed by any
number of bold and italic elements.
Source XML instance:
A portion of the XML file used in this section is shown below. Our area of concern is the mixed
content element "para", along with it's child nodes "bold" and "italic". Please note that the para
element also contains a Processing Instruction (sort alpha-ascending) as well as Comment text
(Company details...) which can also be mapped, see "mixed content settings".
Please note the sequence of the text and bold/italic nodes of Nanonull., Inc in the XML instance
file, they are:
<para> The company...
<bold>Vereno</bold>in 1995 ...
Altova MapForce 2008
© 2008 Altova GmbH
Methods of mapping data (Standard / Mixed / Copy All)
Source driven / mixed content mapping
69
<italic>multi-core...</italic>February 1999
<bold>Nano-grid.</bold>The company ...
<italic>offshore...</italic>to drive...
</para>
Mapping
The initial state of the mapping is shown below.
Output of above mapping:
The result of the initial mapping is shown below: Organization Chart as well as the individual
office names have been output.
© 2008 Altova GmbH
Altova MapForce 2008
70
Methods of mapping data (Standard / Mixed / Copy All)
Default settings: mapping mixed content
5.2
Default settings: mapping mixed content
Creating mixed content connections between items:
1. Select the menu option Connection | Auto Connect matching children to activate
this option, if it is not currently activated.
2. Connect the Desc item in the source schema, with the Desc item in the target schema.
A message appears, asking if you would like to create a mixed content connection. You
are also notified that the text and child items will be transferred in the same order they
appear in the XML source file.
3. Click Yes to create a mixed content connector.
Please note:
Although the Desc element is not of mixed content, a message appears because the
auto-connect option has been activated, and para exists in both source and target
components. Para is of mixed content, and makes the message appear at this point.
The mixed-content message also appears if you only map the para items directly,
without having the autoconnect option activated.
All child items of Desc have been connected. The connector joining the para items is
displayed as a dotted line, to show that it is mixed content.
4. Click the Output tab to see the result of the mapping.
5. Click the word Wrap icon
Altova MapForce 2008
, to view display the complete text in the Output window.
© 2008 Altova GmbH
Methods of mapping data (Standard / Mixed / Copy All)
Default settings: mapping mixed content
71
The mixed content text of each office description has been mapped correctly; the text,
as well as the bold and italic tag content, have been mapped as they appear in the XML
source file.
6. Switch back to the Mapping view.
Removing text nodes from mixed content items:
1. Right click the para connector and select Connection Settings.
The image shows the default settings when you first create mixed content mapping.
The "Map Text content" check box is active per default.
2. Deactivate the Map Text content check box and click OK to confirm.
3. Click the Output tab to see the result of the mapping.
© 2008 Altova GmbH
Altova MapForce 2008
72
Methods of mapping data (Standard / Mixed / Copy All)
Default settings: mapping mixed content
Result:
 all text nodes of the para element have been removed.
 mapped bold and italic text content remain
 bold and italic item sequence still follow that of the source XML file!
Text nodes and mixed content mapping:




Text nodes can only be mapped in their entirety; you cannot limit, or transform the data
they contain. All text nodes of the para element are either mapped, or excluded, as in
the example above.
Filters, or any other type of function, cannot be used to access text node data.
Mixed content child node data, i.e. data enclosed in bold/italic tags in this example, can
of course be mapped individually. If a connector exists, then the child data will be
mapped.
There is currently no way of accessing the text node(s) of a mixed content element, for
further processing, or filtering.
Mixed content settings:
 Right click the para connector and select Connection Settings.
This opens the Connection Settings dialog box in which you can define the specific
(mixed content) settings of the current connector. Note that unavailable options are
greyed out.
Please note that these settings also apply to complexType items which do not have
any text nodes!
Altova MapForce 2008
© 2008 Altova GmbH
Methods of mapping data (Standard / Mixed / Copy All)
Default settings: mapping mixed content
73
Target Driven (Standard)
Changes the connector type to Standard mapping, please see: "Source-driven / mixed content
vs. standard mapping" for more information.
Source Driven (mixed content)
Changes the connector type to source driven / mixed content, and enables the selection of
additional elements to be mapped. The additional elements have to be child items of the
mapped item in the XML source file, to be able to be mapped.
Annotation settings:
Individual connectors can be labeled for clarity.
1. Double click a connector and enter the name of the connector in the Description field.
This enables all the options in the Annotation Settings group.
2. Use the remaining groups to define the position and alignment of the label.
© 2008 Altova GmbH
Altova MapForce 2008
74
Methods of mapping data (Standard / Mixed / Copy All)
5.3
Mixed content example
Mixed content example
The following example is available as "ShortApplicationInfo.mfd" in the C:\Documents and
Settings\<username>\My Documents\Altova\MapForce2008\MapForceExamples folder.
A snippet of the XML source file for this example is shown below.
The mapping is shown below. Please note that:



The Subsection item connector is of mixed content, and is mapped to the Description
item in the target XML/schema.
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.
Altova MapForce 2008
© 2008 Altova GmbH
Methods of mapping data (Standard / Mixed / Copy All)
© 2008 Altova GmbH
Mixed content example
75
Altova MapForce 2008
76
Methods of mapping data (Standard / Mixed / Copy
Source-driven
All)
/ mixed content vs. standard mapping
5.4
Source-driven / mixed content vs. standard mapping
This section describes the results when defining standard mappings (or using standard
connectors) on mixed content items. The files used in the following example (
Tut-Orgchart.mfd) are available in the C:\Documents and Settings\<username>\My
Documents\Altova\MapForce2008\MapForceExamples\Tutorial\ folder.
Creating standard connections between mixed content items:
1. Create a connector element between the two para items.
A message appears, asking if you would like to create a mixed content connection. You
are also notified that the text and child items will be transferred in the same order they
appear in the XML source file.
2. Click No to create a standard mapping.
2. Click the Output tab to see the result of the mapping.
Result:
 all text nodes of the para element have been retained
 mapped bold and italic text content remain
 However, bold and italic item sequence follow that of the target XML/schema file!
Target Driven (Standard) - properties
Standard mapping means the normal method of mapping used in MapForce, i.e.:



Mixed content text node content is supported/mapped, but the start/end tags of the
child nodes are stripped out.
The sequence of child nodes is dependent on the target XML/schema file.
The child nodes appear after the mixed content node text.
In this example:
For each para element, first map all bold items, then map all italic items. This results
Altova MapForce 2008
© 2008 Altova GmbH
Methods of mapping data (Standard / Mixed / CopySource-driven
All)
/ mixed content vs. standard mapping
77
in the child item sequence shown above: bold, bold - italic, italic. The content of each
item is mapped if a connector exists.
Copy-all mapping:
1. Right click the para connector and select Copy-all from the popup window.
The connector now appears as a solid line with the child items branching out of, and
below it. Please see "Copy-all connections" for more information.
© 2008 Altova GmbH
Altova MapForce 2008
78
Methods of mapping data (Standard / Mixed / Copy All)
5.5
Copy-all connections
Copy-all connections
This type of connection allow you to organize your workspace and automatically connect all
identical items in source and target components, meaning that, depending on the source and
target type:

all source child items are copied to the target component, if either the source and
target types are identical, or if the target type is xs:anyType

if the source and target types are not identical, and if the target type is not
xs:anyType, the source data is transferred/mapped to the respective target items of the
same name and the same hierarchy level. If the names of the target items differ, then
the target item is not created.

Note that only the names of the child items, but not their individual types, are
compared/matched.
Currently Copy-all connections are supported:

between XML schema complex types, and

between complex components (XML schema) and complex user-defined
functions/components containing the same corresponding complex parameters, please
see "Complex output components - defining" for an example.
The example below shows these connectors using the MarketingAndDailyexpenses.mfd file
in the C:\Documents and Settings\<username>\My
Documents\Altova\MapForce2008\MapForceExamples folder.
1. Right click the Person component and select "Copy-all" from the context menu.
A prompt appears reminding you that the target connectors will be deleted.
2. Click OK if you want to create Copy-all connectors.
Altova MapForce 2008
© 2008 Altova GmbH
Methods of mapping data (Standard / Mixed / Copy All)
Copy-all connections
79
All connectors to the target component, and all source and target items with identical
names are created.
Please note:
 When the existing target connections are deleted, connectors from other source
components, or other functions are also deleted.

This type of connection cannot be created between an item and the root element of a
schema component.

Individual connectors cannot be deleted, or reconnected from the Copy-all group, once
you have used this method.
Copy-all connections and user-defined functions
When creating Copy-all connections between a schema and a user-defined function 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. Please see "Complex output components defining" for an example.
Copy-all connections and filters
Copy-all connections can also be created through filter components if the source component:



consists of structured data, meaning a schema component.
receives data through a complex output parameter of a user-defined function, or Web
service.
receives data through another filter component.
Only the filtered data is passed on to the target component.
© 2008 Altova GmbH
Altova MapForce 2008
80
Methods of mapping data (Standard / Mixed / Copy All)
Copy-all connections
Copy-all connections through filters cannot be created if the source component:
 is an "exists" type of component
 is a "function" component e.g. "equal"
To define a copy-all connection through a filter component:
1. Right click the filter output connector i.e. the right hand on-true/on-false connector.
2. Select Copy-all (Copy child items) from the context menu.
The copy-all connector between items of the same name are created.
Please note:
To change the connector back to a different type, make sure you right click connector
on the output side of the filter, the left hand connector cannot be used to change the
connection type.
Altova MapForce 2008
© 2008 Altova GmbH
Methods of mapping data (Standard / Mixed / Copy All)
5.6
Connector properties
81
Connector properties
Connectors and their properties:
 Clicking a connector highlights it in red.
 Hitting the Del key, while highlighted, deletes it immediately.
 Right clicking a connector, opens the connector context menu.
 Double clicking a connector, opens the Connection Settings dialog box.
Viewing connectors
MapForce allows you to selectively view the connectors in the mapping window.
Show selected component connectors
Switches between showing:


all mapping connectors in black, or
those connectors relating to the currently selected component in black. Other
connectors appear dimmed.
Show connectors from source to target
Switches between showing:


connectors that are directly connected to the currently selected component, or
connectors linked to the currently selected component, originating from source and
terminating at the target components.
Connector context menu:
Connect matching children
Opens the "Connect Matching Children" dialog box, allowing you to change the connection
settings and connect the items when confirming with OK.
Delete
Deletes the selected connector.
Target Driven (Standard)
Changes the connector type to Standard mapping, please see: "Source-driven / mixed content
vs. standard mapping" for more information.
Copy-all
Changes the connector type to "Copy-all" and connects all child items of the same name in a
graphically optimized fashion, please see "Copy-all connections" for more information.
Source Driven (mixed content)
© 2008 Altova GmbH
Altova MapForce 2008
82
Methods of mapping data (Standard / Mixed / Copy All)
Connector properties
Changes the connector type to source-driven / mixed content, please see: "Source driven and
mixed content mapping" for more information.
Connection settings:
Opens the Connections Settings dialog, in which you can define the specific mixed content
settings as well as the connector annotation settings, please see the Connection section in the
Reference section.
Connect Matching Children dialog box
This command allows you to create multiple connectors between items of the same name in
both the source and target components.
1. Connect two (parent) items that share identically named child items in both
components.
2. Right click the connector and select the Connect matching child elements option.
3. Select the required options discussed in the text below, and click OK to create the
connectors.
Connectors are created for all the child items that have identical names and adhere to
the settings defined in the dialog box.
Please note:
The settings you define here are retained, and are applied when connecting two items,
if the "Auto connect child items" icon
in the title bar is active. Clicking the icon
switches between an active and deactive state.
Ignore Case:
Ignores the case of the child item names.
Ignore Namespaces:
Ignores the namespaces of the child items.
Recursive:
Having created the first set of connectors, the grandchild items are then checked for identical
names. If some exist, then connectors are also created for them. The child elements of these
items are now checked, and so on.
Mix Attributes and Elements:
Allows the creation of connectors between items of the same name, even if they are of different
types e.g. two "Name" items exist, but one is an element, the other an attribute. If set active, a
connector is created between these items.
Altova MapForce 2008
© 2008 Altova GmbH
Methods of mapping data (Standard / Mixed / Copy All)
Connector properties
83
Existing connections:
Ignore existing output connections:
Creates additional connectors to other components, even if the currently existing output icons
already have connectors.
Retain
Retains existing connectors.
Overwrite:
Recreates connectors, according to the settings defined. Existing connectors are scrapped.
Delete all existing:
Deletes all existing connectors, before creating new ones.
Deleting connections
Connectors that have been created using the Connect Matching Children dialog, or during the
mapping process can be removed as a group.
Right click the item name in the component, not the connector itself, Person in this example.
Select Delete Connections | Delete all ... connections.
Delete all direct connections:
Deletes all connectors directly mapped to, or from, the current component to any other source
or target components.
Delete all incoming child connections:
Only active if you have right clicked an item in a target component. Deletes all incoming child
connectors.
Delete all outgoing child connections:
Only active if you have right clicked an item in a source component. Deletes all outgoing child
connectors.
© 2008 Altova GmbH
Altova MapForce 2008
Chapter 6
Global Resources
86
Global Resources
6
Global Resources
Global resources are a major enhancement in the interoperability between products of the
Altova product line, and are currently available in the following Altova products: XMLSpy,
MapForce, StyleVision and DatabaseSpy. Users of the Altova Mission kits have access to the
same functionality in the respective products.
General uses:
 Workflows can be defined that use various Altova applications to process data.
 An application can invoke a target application, initiate data processing there, and route
the data back to the originating application.
 Defining input and output data, file locations , as global resources.
 Switching between global resources during runtime to switch between development or
deployment resources for example.
 What-if scenarios for QA purposes.
The default location of the global resource definitions file, GlobalResources.xml, is c:
\Documents and Settings\UserName\My Documents\Altova\. This is the default location for all
Altova applications that can use global resources. Changes made to global resources are thus
automatically available in all applications. The file name and location can be changed please
see Global Resources - Properties for more information.
General mechanism:
 Global resources are defined in an application and automatically saved.
 Global resources are assigned to components whose data you intend to be variable.
 The global resource is invoked / activated in an application, allowing you to switch
resources at runtime.
This section will describe how to define and use, global resources using existing mappings
available in the C:\Documents and Settings\<username>\My Documents\Altova\MapForce2008
\MapForceExamples\Tutorial\ folder.
To activate the Global Resources toolbar:
Select the menu option Tools | Customize | click the Toolbar tab and activate the Global
Resources check box. This displays the global resources tool bar.
The combo box allows you to switch between the various resources, a "Default" entry is always
available.
Clicking the Global Resources icon
opens the Global Resources dialog box (alternatively
Tools | Global Resources).
Altova MapForce 2008
© 2008 Altova GmbH
Global Resources
6.1
Global Resources - Files
87
Global Resources - Files
Global Resources in MapForce:
 Any input/output components files can be defined as global resources, e.g. XML, XML
Schema, files.
Aim of this section:
 To make the source component input file, mf-ExpReport, a global resource.
 To switch between the two XML files that supply its input data at runtime, and check
the resulting XML output in the Output preview tab.
This section uses the Tut-ExpReport.mfd file available in the C:\Documents and
Settings\<username>\My Documents\Altova\MapForce2008\MapForceExamples
\Tutorial\ folder.
© 2008 Altova GmbH
Altova MapForce 2008
88
Global Resources
Global Resources - Files
6.1.1
Defining / Adding global resources
Defining / Adding a global resource file
1. Click the Global Resource icon
to open the dialog box.
This is the state of an empty global resources file.
2. Click the Add button and select File from the popup.
3. Enter the name of the Resource alias e.g. MultiInput.
4. Click the Open folder icon and select the XML file that is to act as the "Default" input file
e.g. mf-ExpReport.xml.
5. Click the Add button
of the Configurations group, to add a new configuration to the
current Alias. Note that the Copy configuration icon
configuration and save it under a new name.
Altova MapForce 2008
, allows you to copy a selected
© 2008 Altova GmbH
Global Resources
Global Resources - Files
89
6. Enter a name for the configuration, Multi2nd, and click OK to confirm.
Multi2nd has now been added to the Configurations list.
7. Click the Open folder icon again and select the XML file that is to act as the input file for
the multi2nd configuration e.g. mf-ExpReport2.xml.
8. Click OK to complete the definition of the resource.
The MultiInput alias has now been added to the Files section of the global resources.
Placing the mouse cursor over an alias entry, opens a tooltip showing its defintion.
© 2008 Altova GmbH
Altova MapForce 2008
90
Global Resources
Global Resources - Files
9. Click OK to confirm.
This concludes the definition part of defining global resources. The next step is
Assigning a global resource to a component.
Altova MapForce 2008
© 2008 Altova GmbH
Global Resources
6.1.2
Global Resources - Files
91
Assigning a global resource
Assigning global resources to a component
We now have to assign the global resource to the component that is to make use of it.
1. Double click the mf-ExpReport component and click the global resource icon next to
the Input XML-Instance field.
This opens the "Choose Global Resource" dialog box.
2. Click the resource you want to assign, MultiInput in this case, and click OK.
The Input XML-Instance field now contains a reference to a resource i.e. altova://
file_resource/MultiInput.
3. Click OK to complete the assignment of a resource to a component.
The next step is Using / activating a global resource.
© 2008 Altova GmbH
Altova MapForce 2008
92
Global Resources
6.1.3
Using / activating a global resource
Global Resources - Files
Using / activating a global resource
At this point the previously defined Default configuration for the MultiInput Alias is active. You
can check this by noting that the entry in the Global Resources icon bar is "Default".
1. Click the Output tab to see the result of the mapping.
2. Click the global resources combo box and select Multi2nd from the combo box.
A message box opens stating that an input file has changed and prompts if you want
to regenerate the output.
3. Click Yes to use the XML file defined by the multi2nd configuration.
Altova MapForce 2008
© 2008 Altova GmbH
Global Resources
Global Resources - Files
93
The mf-ExpReport2.xml file is now used as the source component for the mapping, and
produces different output.
Note:
The currently active global resource (multi2nd in the global resources toolbar)
determines the result of the mapping. This is also the case when you generate code.
You can change the currently active resource while in the Output tab, there is no need
to return to the mapping tab and click Output again.
© 2008 Altova GmbH
Altova MapForce 2008
94
Global Resources
6.2
Global Resources - Folders
Global Resources - Folders
Folders can also be defined as a global resource, which means that input components can
contain files that refer to different folders, for development and release cycles for example.
Defining folders for output components is not really useful in MapForce, as you are always
prompted for the target folders when generating XSLT or code for other programming
languages.
The mapping file used in this section is available as "global-folder.mfd" in the C:\Documents
and Settings\<username>\My Documents\Altova\MapForce2008\MapForceExamples\Tutorial\
folder.
Defining / Adding global resource folders
1. Click the Global Resource icon
to open the dialog box.
2. Click the Add button and select Folder from the popup.
3. Enter the name of the Resource alias e.g. Dev_Release.
4. Click the Open folder icon and select the "Default" input folder, ...\MapForceExamples.
5. Click the Add button
of the Configurations group, to add a new configuration to the
current Alias, and enter a name for it e.g. Release. Note that the Copy configuration
icon
, allows you to copy a selected configuration and save it under a new name.
6. Click the Open folder icon and select the Release input folder, ...\MapForceExamples
\Tutorial.
7. Click OK to finish the global folder definition.
Assigning the global resource folders:
1. Double click the ExpReport component and click the global resource icon
the Input XML-Instance field.
Altova MapForce 2008
next to
© 2008 Altova GmbH
Global Resources
Global Resources - Folders
95
2. Click the resource you want to assign, Dev_Release in this case, and click OK.
The "Open..." dialog appears.
3. Select the file name that is to act as both the Development and Release resource file
in each of the folders, e.g. ExpReport.xml and click OK to finish assigning the resource
folder.
Note that this file is available in both directories but has different content.
Changing the resource folder at runtime:
1. Click the Output tab to see the result of the transformation.
Note that this is the Default configuration/folder .../MapforceExamples.
© 2008 Altova GmbH
Altova MapForce 2008
96
Global Resources
Global Resources - Folders
2. Click the Global Resource combo box and select the "Release" entry.
3. Click Yes when the prompt asks if you want to regenerate the output.
The output from the "Release" folder .../MapforceExamples/Tutorial is now displayed.
Altova MapForce 2008
© 2008 Altova GmbH
Global Resources
6.3
Global Resources - Application workflow
97
Global Resources - Application workflow
The aim of this section is to create a workflow situation between two Altova applications.
Workflow is initiated in XMLSpy which starts MapForce and passes the generated XML file
output back to XMLSpy for further processing.
This mapping uses two output components to produce two types of filtered output; Travel and
Non-travel expenses of the expense report input file. This section uses the Tut-ExpReportmulti.mfd mapping file available in the C:\Documents and Settings\<username>\My Documents
\Altova\MapForce2008\MapForceExamples\Tutorial\ folder.
1.
2.
3.
4.
Click the Global Resource icon
to open the dialog box.
Click the Add button and select File from the popup.
Enter the name of the Resource alias e.g. MultiOutput2Spy
Click the "Result of MapForce Transformation" radio button and select the TutExpReport-multi.mfd mapping.
MapForce analyzes the mapping and displays the input and output files in separate list
boxes. Placing the mouse cursor over a path, displays the full path (and file name) in a
tooltip.
© 2008 Altova GmbH
Altova MapForce 2008
98
Global Resources
Global Resources - Application workflow
5. Click the top radio button entry in the Outputs section, if not already selected.
Note that the output file name is ExpReport-Target.xml and that we are currently
defining the Default configuration.
6. Click the "Save as" icon
to define the new location of the output file, and select
Browse... from the popup menu.
7. Enter the new output location e.g. C:\Temp. This location can differ from the location
defined in the component settings.
8. Click the Add button
of the Configurations group, to add a new configuration to the
resource alias.
9. Enter the name of the configuration, e.g. Output2, and click the lower radio button of
the Outputs listbox. Note that the output file name is SecondXML.xml.
Altova MapForce 2008
© 2008 Altova GmbH
Global Resources
10. Click the "Save as" icon
Global Resources - Application workflow
99
to define the new location of the output file e.g. C:\Temp.
Note: clicking the "Choose another Global Resource... in the popup, allows you to
save the MapForce output as a global resource. I.e. the output is stored to a file that the
global resource physically points to/references.
11. Click OK to save the new global resources.
The new resource alias MultiOutput2Spy has been added to the Global Resources
definition file.
© 2008 Altova GmbH
Altova MapForce 2008
100
Global Resources
Global Resources - Application workflow
12. Click OK to complete the definition phase.
Altova MapForce 2008
© 2008 Altova GmbH
Global Resources
6.3.1
Global Resources - Application workflow
101
Start application workflow
This section shows how the Global Resource is activated in XMLSpy and how the resulting
MapForce transformation is routed back to it.
1. Start XMLSpy and shut down MapForce, if open, to get a better view of how the two
applications interact.
2. Select the menu option File | Open Global Resource in XMLSpy.
3. Select MultiOutput2Spy and click OK.
A message box stating that MapForce is transforming appears, with the result of the
transformation appearing in the Text view window.
Note:
 The currently selected configuration is "Default".
© 2008 Altova GmbH
Altova MapForce 2008
102
Global Resources



Global Resources - Application workflow
The name of the resource alias is in the application title bar altova://file_resource/
MultiOutput2Spy.
The output file has been opened as "Untitled1.xml" for further processing.
The ExpReport-Target.xml file has been copied to the C:\Temp folder.
To retrieve the non-travel expenses output:
1. Click the Global Resources combo box and select "Output2".
A Changed file notification message box opens.
2. Click Reload to retrieve the second output file defined by the resource.
The result of the transformation appears in the Text view window and overwrites the
previous Untitled1.xml file.
Note:
 The currently selected configuration is "Output2"
Altova MapForce 2008
© 2008 Altova GmbH
Global Resources


Global Resources - Application workflow
103
The output file has been opened as "Untitled1.xml" for further processing.
The SecondXML.xml file has been copied to the C:\Temp folder.
© 2008 Altova GmbH
Altova MapForce 2008
104
Global Resources
6.4
Global Resources - Properties
Global Resources - Properties
The Global Resources XML File
Global resources definitions are stored in an XML file. By default, this XML file is called
GlobalResources.xml, and it is stored in the folder C:\Documents and Settings
\<username>\My Documents\Altova\. This file is set as the default Global Resources XML
File for all Altova applications. As a result, a global resource defined in any application will be
available to all Altova applications—assuming that all applications use this file.
You can also re-name the file and save it to any location. You can therefore have multiple
Global Resources XML files. However, only one of these Global Resources XML File can be
active, per application, at one time, and only the definitions contained in this file will be available
to the application.
To make the Global Resources XML file active, browse from the "Definitions file" and select the
one you want to use from the "Open..." dialog box.
Whenever changes are made to the Global Resources XML file in one application, a message
box is automatically opened in the other, (running application) stating that the definition file was
modified. You are prompted if you want to reload the file; options are Yes or No.
Managing global resources: adding, editing, deleting
In the Global Resources dialog, you can add a global resource to the selected Global
Resources XML File, or edit or delete a selected global resource. The Global Resources XML
File organizes the aliases you add into the following sections: files, folders.
To add a global resource, click the Add button and define the global resource in the Global
Resource dialog that pops up. After you define a global resource and save it, the global
resource (or alias) is added to the list of global definitions in the selected Global Resources
XML File.
To edit a global resource, select it and click Edit. This pops up the Global Resource dialog, in
which you can make the necessary changes.
To delete a global resource, select it and click Delete.
Having finished adding, editing, or deleting, make sure to click OK in the Global Resources
Altova MapForce 2008
© 2008 Altova GmbH
Global Resources
Global Resources - Properties
105
dialog to save your modifications to the Global Resources XML File.
Note: Alias resource names must be unique within each of the Files, Folders. You can however
define an identical alias name in two different sections, e.g. a multiInput alias can exist in the
Files section as well as in the Folders section.
Selecting Results of MapForce transformations as a global resource
In a MapForce transformation that has multiple outputs, you can select which one of the output
files should be used for the global resource by clicking its radio button.
The output file that is generated by the mapping can be saved as:

a global resource via the Choose another Global Resource entry in the popup, visible
as altova://file_resource/MF_output. The output is stored to a file that the global
resource physically points to/references.

a file via the
icon, shown as C:\TEMP\Second.xml.
If neither of these options is selected, a temporary XML file is created when the global
resource is used.
Determining which resource is used at runtime
There are two application-wide selections that determine what global resources can be used
and which global resources are actually used at any given time:

The active Global Resources XML File is selected in the Global Resource dialog. The
active Global Resources XML File can be changed at any time, and the global-resource
definitions in the new active file will immediately replace those of the previously active
file.
The active Global Resources XML File therefore determines: (i) what global resources
can be assigned, and (ii) what global resources are available for look-up (for example, if
a global resource in one Global Resource XML File is assigned but there is no global
resource of that name in the currently active Global Resources XML File, then the
assigned global resource (alias) cannot be looked up).

The active configuration is selected via the menu item Tools | Active Configuration or
via the Global Resources toolbar. Clicking this command (or dropdown list in the
toolbar) pops up a list of configurations across all aliases.
Selecting a configuration makes that configuration active application-wide. This means
© 2008 Altova GmbH
Altova MapForce 2008
106
Global Resources
Global Resources - Properties
that wherever a global resource (or alias) is used, the resource corresponding to the
active configuration of each used alias will be loaded.
The active configuration is applied to all used aliases. If an alias does not have a
configuration with the name of the active configuration, then the default configuration
of that alias will be used. The active configuration is not relevant when assigning
resources; it is significant only when the resources are actually used.
Changing resources / configurations
Resources can be switched by selecting a different configuration name. This can be done in two
ways:

When you hover over the menu command Tools | Active Configuration, a submenu
with a list of all configurations in the Global Resources XML File appears. Select the
required configuration from the submenu.

In the combo box of the Global Resources toolbar, select the required configuration.
The Global Resources toolbar can be toggled on and off with the menu command
Tools | Customize, then click the Toolbar tab and enable/disable the Global
resources check box.
Altova MapForce 2008
© 2008 Altova GmbH
Chapter 7
How To... Filter, Transform, Aggregate
108
How To... Filter, Transform, Aggregate
7
How To... Filter, Transform, Aggregate
This section deals with common tasks that will be encountered when creating your own
mappings.
The tasks covered are:

 Using the Value-Map function to transform data

 Using aggregate functions, min, max, sum
 Using boolean values in XSLT 1.0
 Boolean comparison of input nodes

 Defining the Priority context

 MapForce command-line parameters
 Using input functions to override values, and act as parameters in command line
execution

 Checking for existing / not existing nodes
 Type conversion checking
 How to define and use exceptions

Altova MapForce 2008
© 2008 Altova GmbH
How To... Filter, Transform, Aggregate
7.1
Value-Map - transforming input data
109
Value-Map - transforming input data
The Value-Map component allows you to transform an input value to a different output value
using a lookup table. This is useful for converting different enumeration types. The component
only has one input and output item.
Note: if you want to retrieve/filter data based on specific criteria, please use the Filter
component see Filtering XML data: Filtering data.
To use a Value-Map component:
1. Select the menu option Insert | Value-Map, or click the Value-Map icon
bar.
in the icon
2. Double click the Value-Map component to open the value map table.
3.
4.
5.
6.
Enter the input value that you want to transform, in the input column.
Enter the output value you want to transform that value to, in the result column.
Simply type in the (new entry) input field to enter a new value pair.
Click the datatype combo box to select the input and result datatypes, e.g. integer and
string.
© 2008 Altova GmbH
Altova MapForce 2008
110
How To... Filter, Transform, Aggregate
Value-Map - transforming input data
7. Activate the Otherwise check box to define an alternative output value if the supplied
values are not available on input.
8. You can click the edit icons in the header rows to change the column names, which are
also displayed in the mapping. This will make it easier to identify the purpose of the
component in the mapping.
The Expense-valmap.mfd file in the C:\Documents and Settings\<username>\My
Documents\Altova\MapForce2008\MapForceExamples\Tutorial\ folder is a sample mapping
that shows how the Value-Map can be used.
What this mapping does:
Extracts the day of the week from the Date item in the data source, converts the numerical
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 top Value-Map component transforms the integers into weekdays, i.e. Sunday,
Monday, etc. as shown in the graphic at the top of this section.
The output of the Value-Map component is mapped to the Weekday item in the target
component, as well as to the value item of the contains function.
If the output contains "Tuesday", as supplied by the Constant component connected to
the substring parameter, then the corresponding output "Prepare Financial Reports" is
mapped to the Notes item in the target component.
Altova MapForce 2008
© 2008 Altova GmbH
How To... Filter, Transform, Aggregate


Value-Map - transforming input data
111
Note that the output from various types of logical, or string functions, can only be a
boolean "true" or "false" value. The value you want to test for, must thus be entered
into the input field of the value map table e.g. true.
Clicking the Output tab displays the target XML file with the transformed data.
© 2008 Altova GmbH
Altova MapForce 2008
112
How To... Filter, Transform, Aggregate
7.1.1
Value-Map component properties
Value-Map - transforming input data
Actions:
Click the insert icon to insert a new row before the currently active one.
Click the delete icon to delete the currently active row.
Click the edit icon to edit the column header.
You can also reorder lines by dragging them.
Changing the column header:
Double clicking the column header, or clicking the pencil icon, allows you to edit the column
name and change it to something more meaningful. This will make it easier to identify the
purpose of the component, as the column names are also displayed in the mapping.
Using unique Input values:
The values entered into the input column must be unique. If you enter two identical values, both
are automatically highlighted for you to enable you to correct one of them.
Having corrected one of the values, the OK button is again enabled.
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.
Altova MapForce 2008
© 2008 Altova GmbH
How To... Filter, Transform, Aggregate
Value-Map - transforming input data
113
In the screenshot below a boolean and string have been selected.
© 2008 Altova GmbH
Altova MapForce 2008
114
How To... Filter, Transform, Aggregate
7.2
Aggregate functions: min, max, sum
Aggregate functions: min, max, sum
Aggregate functions perform operations on a set of input values (or a sequence of values) as
opposed to a single value. The most obvious ones are min, max, count, avg (average), and
sum. The aggregate functions can all be found in the core library. The mapping shown below is
available as Aggregates.mfd in the ...\Tutorial folder.
Please also see Aggregate functions - summing nodes in XSLT1 and 2 on how to create
aggregate functions using Named Templates.
Aggregate functions have two input items.
 values is connected to the source item that provides the data, in this case Number.
 in-context is connected to the item you want to iterate over, in this case over all
Customers.
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.
Altova MapForce 2008
© 2008 Altova GmbH
How To... Filter, Transform, Aggregate
Aggregate functions: min, max, sum
115
Clicking the Output tab for the above mapping delivers the following result:
© 2008 Altova GmbH
Altova MapForce 2008
116
How To... Filter, Transform, Aggregate
Mappings and root element of target documents
7.3
Mappings and root element of target documents
Root element of target XML files
When creating a mapping to the root element of the target Schema/XML file, please make sure
that only one element is passed on to the target XML, as an XML document may only have one
root element.
Use the filter component to limit the mapped data to a single element or record.
Root element not limited:
If you do not limit the target schema root element, then all source elements/records are inserted
between the first root element. This will still create well-formed, but not valid, XML files.
Altova MapForce 2008
© 2008 Altova GmbH
How To... Filter, Transform, Aggregate
7.4
Boolean values and XSLT 1.0
117
Boolean values and XSLT 1.0
XSLT 1.0 processors can only process values as strings or numbers. The values supplied by
the "detailed" element in this example, can only be "true" or "false" (as defined in the schema
file).
The example below tries to create an IF-ELSE construct, using the bool value of "detailed".
Depending on the content, you should either see the First, or Last name of the Person element
in the Target schema.
Trying out this mapping however, shows that whatever the bool value of detailed is, true or
false, you will always have the contents of First in the target schema. XSLT currently takes all
string input as True, so this method cannot be used to directly check a boolean value.
Clicking the "Insert Condition" icon
inserts the IF-Else condition function.
To use boolean values as comparison values in XSLT:
1. Supply a boolean value using the constant component, e.g. true.
2. Use the equal component to check if the value of the constant, is equal to the content
of the boolean node, detailed.
3. Pass the result of the comparison on to the bool parameter of the if-else condition.
If the detailed element supplies true, then the equal result parameter is also true.


If the bool value (of if-else) is true, then the value of First is passed on to the target
schema.
If false, then the value of Last is passed on to the target schema.
© 2008 Altova GmbH
Altova MapForce 2008
118
How To... Filter, Transform, Aggregate
Boolean values and XSLT 1.0
Forcing boolean values:
There might be instances where you want to predefine, or force the result of a condition.
1. Connect the constant component directly to the bool parameter of an if-else/filter
component.
2. Select the Number radio button in the "Insert constant" dialog box, and
3. Enter 1 for True, and 0 for false - depending on the condition you want satisfied.
Altova MapForce 2008
© 2008 Altova GmbH
How To... Filter, Transform, Aggregate
7.5
Boolean comparison of input nodes
119
Boolean comparison of input nodes
Data type handling in boolean functions (first introduced with MapForce 2006 SP2)
During the evaluation of the core functions, less-than, greater-than, equal, not-equal, less equal,
and greater equal, the evaluation result of two input nodes depends on the input values as well
as the data types used for the comparison.
Example:
The 'less than' comparison of the integer values 4 and 12, yields the boolean value "true", since
4 is less than 12. If the two input strings contain '4' and '12', the lexical analysis results in the
output value false", since '4' is alphabetically greater than the first character '1' of the second
operand (12).
If all "input" data types are of the same type, e.g. all input nodes are numerical types, or strings,
then the comparison is done for the common type.
Differing input node types
If the input nodes are of differing types, e. g. integer and string, or string and date, then the
following rule is applied:
The data type used for the comparison is always the most general, i. e. least restrictive,
input data type of the two input types.
Before comparing two values, all input values are converted to a common datatype. Using the
previous example; the datatype "string" is less restrictive than "integer". Comparing integer
value 4 with the string '12', converts integer value 4 to the string '4', which is then compared with
the string '12'.
The type handling for comparing mixed types, follows the XSLT2 guidelines and prevents any
content-sensitive type conversion strategies. The advantage is that the logic is fixed by the
mapping and does not change dynamically.
Additional checks:
Version SP2 additionally checks mappings for incompatible combinations and raises validation
errors and warnings if necessary. Examples are the comparison of dates with booleans, or
"datetimes" with numerical values.
In order to support explicit data type conversion, the following type conversion functions are
available in the core library: "boolean", "number" and "string". In the previously mentioned
context, these three functions are suitable to govern the interpretation of comparisons.
Adding these conversion functions to input nodes of related functions might change the
common data type and the result of the evaluation in the desired manner. E. g. if string nodes
store only numeric values, a numerical comparison is achieved by adding the "number"
conversion function (in the conversion section of the core library) to each input node.
© 2008 Altova GmbH
Altova MapForce 2008
120
How To... Filter, Transform, Aggregate
7.6
Priority Context
Priority Context
When applying a function to different items in a schema, MapForce needs to know what the
context node will be. All other items are then processed relative to this one. This is achieved by
designating the item (or node) as the priority context.
The CompletePO.mfd file available in the C:\Documents and Settings\<username>\My
Documents\Altova\MapForce2008\MapForceExamples folder, is shown below.
Please note that there are multiple source components in this example. ShortPO, Customers,
and Articles are all schemas with associated XML instance files. The data from each, are then
mapped to the CompletePO schema / XML file. The priority context icon, is enclosed in a circle
as a visual indication.






The CustomerNr in ShortPO is compared with the item Number in the Customers file.
CustomerNr has been designated as the priority context, and is placed in the a
parameter of the equal function.
The Customers file is then searched (once) for the same number. The b parameter
contains the Number item from the Customers file.
If the number is found, then the result is passed to the bool parameter of the filter
function.
The node/row parameter passes on the Customers data to "on-true" when the bool
parameter is true, i.e. when the same number has been found.
The rest of the customer data is then passed on as: Number, FirstName, LastName
items, are all connected to the corresponding items in the target schema.
Designating the b parameter of the equal function (i.e. item Number), as the priority context
would cause:
 MapForce to load the first Number into the b parameter
 Check against the CustomerNr in a, if not equal,
 Load the next Number into b, check against a, and
 Iterate through every Number in the file while trying to find that number in ShortPO.
Altova MapForce 2008
© 2008 Altova GmbH
How To... Filter, Transform, Aggregate
7.7
Command line parameters
121
Command line parameters
The command line parameter syntax for MapForce is shown below.
General syntax:
MapForce.exe filename [ /target outputdir [ /GLOBALRESOURCEFILE globalresourcefilename
] [ /GLOBALRESOURCECONFIG configurationname ] [ /LOG logfilename ] ]
target



{ XSLT | XSLT2 }
The square brackets [...] denote optional parameters.
The curly brackets {...} denote a parameter group containing several choices.
The pipe symbol | denotes OR, e.g. /XSLT or /JAVA
Description of general parameters:
filename
outputdir
/LOG logfilename
path and YourMAPFORCEfile.MFD
If the path, or file name contains a space, please use
quotes around the path/file name i.e. "c:\Program
Files\...\Filename"
directory the log file is to be placed in
generates a log file
Description of target parameters:
/XSLT
/XSLT2
generates XSLT1 code
generates XSLT2 code
Description of global resource parameters:
/GLOBALRESOURCEFILE globalresourcefilename uses the global resources defined in the
specified global resource file
/GLOBALRESOURCECONFIG configurationname uses the specified global resource
configuration
Examples:
MapForce.exe filename starts MapForce and opens the file defined by filename.
I) generate all XSLT files and output a log file.
MapForce.exe filename /XSLT outputdir /LOG logfilename
II) generate all XSLT files and use all global resources of the global resource file for the
specified configuration
Mapforce.exe filename /XSLT outputdir /GLOBALRESOURCEFILE
globalresourcefilename /GLOBALRESOURCECONFIG configurationname
© 2008 Altova GmbH
Altova MapForce 2008
122
How To... Filter, Transform, Aggregate
Input values, overrides and command line parameters
7.8
Input values, overrides and command line parameters
MapForce allows you to create special input components that can:


act as a parameter in the command line execution of the compiled mapping, or
define an override, or alternative, value for data being input by the current mapping.
Please note:
This specific type of input component cannot be used inside a user-defined function, it
is only available in the main mapping.
The mapping below, uses such an input component. The aim of this mapping is to search for a
specific article number, and replace it with a value 1033, if found. If the search is not successful,
retain the current number.
What the input component allows you to do, is override the current input which is 1, and replace
it with whatever you define in the input component. Please note that the input in this example is
a constant, i.e. 1, but that this will generally not be the case in a complex mappings, where the
input can be any type of data from any input source.
The input component further doubles as an input parameter for the command line execution of
the generated mapping code!
The above example uses the Articles.xsd schema and Articles.xml files, available in the
C:\Documents and Settings\<username>\My
Documents\Altova\MapForce2008\MapForceExamples folder. The article numbers in the
source XML file are 1, 2, 3, and 4.
1. Use the menu option Function | Insert Input to insert the component.
This opens the Create Input dialog box.
2. Enter a name for the function and select the datatype you want to use.
3. Click in the Value field, of the Preview Settings group, and enter a value. In this case,
enter a value different from the one supplied by the constant, e.g. 2.
Altova MapForce 2008
© 2008 Altova GmbH
How To... Filter, Transform, Aggregate
Input values, overrides and command line parameters
123
4. Click the Output tab to see the result of the mapping.
The original article number 2, has been changed to 1033. The value supplied by the
input component i.e. 2, has taken precedence over the value supplied by the constant,
which was 1.
Input values and Code generation:
The preview settings entered in the "Create/Edit input" dialog box are only applicable when
previewing results in the Output tab. They are not used for code generation or command line
execution of mappings.
The value supplied by the "default" input item/icon is used for the preview, if "Specify value" is
inactive. Code generation and command line execution uses this default value if the
parameter is not supplied on the command line.
Using input values as parameters in command line execution of mappings:
Input values can be used as parameters when calling the generated mapping. In this example,
© 2008 Altova GmbH
Altova MapForce 2008
124
How To... Filter, Transform, Aggregate



Input values, overrides and command line parameters
the generated application name is Mapping.exe
the input value name "TrueVal" is the first parameter, and
the input value "2" is the second parameter.
The command line thus becomes:
mapping.exe /TrueVal 2
Please note:
Running mapping.exe without parameters, displays a warning message, and help on
the command line syntax needed.
Altova MapForce 2008
© 2008 Altova GmbH
How To... Filter, Transform, Aggregate
7.9
Node testing, exists / not-exist
125
Node testing, exists / not-exist
The node testing functions allow you to test for the existence of nodes in the XML instance
files. Elements or attributes defined as optional in the XML Schema, may, or may not, appear in
the XML instance file. Use these functions to perform the specific node test and base further
processing on the result.
Exists
Returns true if the node exists, else returns false.
The "HasMarketingExpenses.mfd" file in the C:\Documents and Settings\<username>\My
Documents\Altova\MapForce2008\MapForceExamples folder contains the small example
shown below.
If an expense-item exists in the source XML, then the "hasExpenses" attribute is set to "true" in
the target XML/Schema file.
Not-exists
Returns false if the node exists, else returns true. Please see Mapping missing nodes - using
Not-exists for an example on how to map missing nodes.
substitute-missing
This function is a convenient combination of exists and a suitable if-else condition. Used to
map the current field content if the node exists in the XML source file, otherwise use the item
mapped to the "replace-with" parameter.
In the image above, the existence of the node "Phone" is checked in the XML instance file. If
the node is not present, then the value supplied by the constant is mapped.
© 2008 Altova GmbH
Altova MapForce 2008
126
How To... Filter, Transform, Aggregate
Altova MapForce 2008
Node testing, exists / not-exist
© 2008 Altova GmbH
How To... Filter, Transform, Aggregate
7.9.1
Node testing, exists / not-exist
127
Mapping missing nodes - using Not-exists
The example below shows how you can use the not-exists function to map nodes that do not
exist in one of a pair of source files.
What this mapping does is to:



Compare the nodes of two source XML files
Filter out the nodes, of the first source XML file, that do not exist in the second source
XML file
Map only the missing nodes, and their content, to the target file.
© 2008 Altova GmbH
Altova MapForce 2008
128
How To... Filter, Transform, Aggregate
Node testing, exists / not-exist
The two XML instance files are shown below, the differences between them are:
 a.xml at left, contains the node <b kind="3">, which is missing from b.xml.
 b.xml at right, contains the node <b kind="4"> which is missing from a.xml.
a.xml



b.xml
The equal function compares the kind attribute of both XML files and passes the result
to the filter.
A not-exists function is placed after the initial filter, to select the missing nodes of each
of the source files.
The second filter is used to pass on the missing node and other data only from the a.
xml file to the target.
The mapping result is that the node missing from b.xml, <b kind="3">, is passed on to
the target component.
Altova MapForce 2008
© 2008 Altova GmbH
How To... Filter, Transform, Aggregate
7.10
Using DTDs as "schema" components
129
Using DTDs as "schema" components
MapForce 2006 SP2 and above, support namespace-aware DTDs for source and target
components. The namespace-URIs are extracted from the DTD "xmlns"-attribute declarations,
to make mappings possible.
Adding DTD namespace URIs
There are however some DTDs, e.g. DTDs used by StyleVision, which contain xmlns*-attribute
declarations, without namespace-URIs. These DTDs have to be extended to make them
useable in MapForce.

The DTD has to be altered by defining the xmlns-attribute with the namespace-URI as
shown below:
<!ATTLIST fo:root
xmlns:fo CDATA #FIXED 'http://www.w3.org/1999/XSL/Format'
...
>
© 2008 Altova GmbH
Altova MapForce 2008
130
How To... Filter, Transform, Aggregate
7.11
Type conversion checking
Type conversion checking
From MapForce 2006 SP2 on, the generated applications and preview (with the builtin
execution engine) check for type-conversion errors in more detail, inline with XSLT2 and
XQUERY.
Converting values from one type to another may now result in a runtime-error, where in prior
versions of MapForce would have produced some type of result.
Example: conversion of a xs:string 'Hello', to xs:decimal
MapForce 2006 Versions up to, and including SP1:
XSLT:
XSLT2:
Xquery:
Preview with
BUILTIN-engine:
C++ app:
C# app:
Java app:
'Hello' (or 'NaN' when passed to a function dealing with
number)
error: "invalid lexical value"
error: "invalid lexical value"
0
0
error: "values not convertable"
error: "values not convertable"
MapForce 2006 SP2:
XSLT:
XSLT2:
Xquery:
Preview with
BUILTIN-engine:
C++ app:
C# app:
Java app:
'Hello' (or 'NaN' when passed to a function dealing with
number)
error: "invalid lexical value"
error: "invalid lexical value"
error: "string-value 'Hello' could not be converted to
decimal"
error: "values not convertable"
error: "values not convertable"
error: "values not convertable"
If type-conversion-errors occur, check that the types have been handled correctly. E.g. use the
lang:numeric() function, to check if the source-value may be converted into a number, and then
an if-else component to pass a different value in case it fails (e.g. a constant containing -1, on
the value-false parameter).
Altova MapForce 2008
© 2008 Altova GmbH
How To... Filter, Transform, Aggregate
7.12
MapForce Exceptions
131
MapForce Exceptions
MapForce provides support for the definition of exceptions. You can define the condition that
will throw an error. When the condition is satisfied, a user-defined message appears and the
mapping process is stopped. The ExpenseLimit.mfd file in the C:\Documents and
Settings\<username>\My Documents\Altova\MapForce2008\MapForceExamples folder is a
sample mapping that contains an exception function.
To insert an exception component:

Select the menu option Insert | Exception, or click the Exception icon
bar.
in the icon
The example above shows how exceptions are defined in mappings. The exception should be
triggered when the Last name of a person equals "Matise".




The equal component checks to see if Last equals Matise, and the bool result is
passed on to the filter component.
When the condition is satisfied, i.e. Matise is True, the on-true parameter of the filter
component activates the exception and the mapping process is stopped. (Note that you
can also connect the exception to the on-false parameter, if that is what you need.)
The error text supplied by the constant component is output.
The error text appears in the Output tab, and also when running the compiled code.
Please note:
It is very important to note the filter placement in the example:

Both parameters of the filter component, on-true and on-false, must be mapped! One
of them needs to be mapped to the exception component, and the other, to the target
component that receives the filtered source data. If this is not the case, the exception
component will never be triggered.

The exception and target components must be directly connected to the filter
© 2008 Altova GmbH
Altova MapForce 2008
132
How To... Filter, Transform, Aggregate
MapForce Exceptions
component. Functions, or other components, may not be placed between the filter and
either the exception, or target components.

When generating XSLT 2.0 and XQuery code, the exception appears in the Messages
window, and a Preview failed message box appears. Clicking the OK button in the
message box switches to the respective XSLT2 or XQuery tab, and the line that
triggered the exception is automatically highlighted.
Altova MapForce 2008
© 2008 Altova GmbH
Chapter 8
Defining User-defined functions
134
Defining User-defined functions
8
Defining User-defined functions
MapForce allows you to create user-defined functions visually, just like the main mapping. This
allows you to organize your mapping into smaller building blocks, and to reuse these building
blocks in other mappings.
User-defined functions can contain any number of input and outputs where any of these can be
in the form of: simple values, or XML nodes.
There are two types of user-defined functions: those defined as "Inline" and the others as
"Standard", please see Inline vs. Standard user-defined functions for more information. Also
note that user-defined functions can be changed from the one type to the other.
The main use of user-defined functions is to combine data sources and processing functions
into a single user-defined function / component, which can be used across different mappings.
User-defined functions can be:
 built from scratch, or
 use functions currently available in the mapping tab.

imported into other mappings by loading the mapping file as a library.
User-defined functions are stored in the *.mfd file, alongside the main mapping.
This example uses the Tut-ExpReport.mfd file available in the C:\Documents and
Settings\<username>\My Documents\Altova\MapForce2008\MapForceExamples folder.
To create a user-defined function:
1. Drag to mark both the concat and the constant components (you can also hold down
the CTRL key and click the functions individually).
2. Select the menu option Function | Create User-Defined Function from Selection.
3. Enter the name of the new user-defined function (First_Last).
Note: valid characters are: alphanumeric, a-z, A-Z, 0-9 as well as underscore "_",
hyphen/dash "-" and colon ":".
4. Use the Syntax and Detail fields to add extra information on the new function, and click
OK to confirm.
The library name "user" is supplied as a default, you can of course define your own
library name in this field.
Altova MapForce 2008
© 2008 Altova GmbH
Defining User-defined functions
135
The individual elements that make up the function group appear in a tab with the
function 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 two components
have now been combined into a single function component called First_Last.
User-defined functions of type "Inline" are displayed with a dashed outline.
© 2008 Altova GmbH
Altova MapForce 2008
136
Defining User-defined functions
Connect the First and Last items to the input parameters of the user-defined function,
and the result parameter to the Name item. Dragging on the function name in the
Libraries pane and dropping it in the mapping window, allows you to use it elsewhere.
Please note:
Double-clicking the title bar of a user-defined function displays the individual
components in a tab of that name. User-defined functions can be defined to contain
complex inputs/outputs (XML nodes etc.) as well as multiple output components.
Please see "Standard user-defined function" and "Complex user-defined function" for
more information.
To delete a user-defined function from a library:
1. Double click the specific user-defined function in the Libraries window.
The user-defined function is visible in its tab.
2. Click the Erase button in the title bar to delete the function.
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 radio button of the
type you want to change it to, Standard or Inline.
Reusing - exporting and importing User-defined functions:
User-defined functions, defined in one mapping, can be imported into any other mapping:
1. Click the Add/Remove Libraries button, at the base of the Libraries pane, and select a
previously saved *.mfd file that contains the user-defined function(s) you want to
import.
The user-defined functions now appear in the Libraries window (under "user" if that is
the default library you selected). You can of course enter anything in the "Library name"
when defining the user-defined function.
2. Drag the imported function into the mapping to make use of it.
Library Names
Note: It is possible to use the same library name for user-defined functions in multiple
*.mfd files and/or custom libraries (see section). Functions from all available sources
will appear under the same library header in the Libraries pane. However, only the
functions in the currently active document can be edited by double-clicking.
In the following example:
Altova MapForce 2008
© 2008 Altova GmbH
Defining User-defined functions
137
 the function "hello" in the "helloworld" library is imported from a custom *.mff library,
 the function "Join" in the "helloworld" library is a user-defined function defined in the
current *.mfd file and
 the function "MyUDF" in the "user" library is also a user-defined function defined in
the current *.mfd file
© 2008 Altova GmbH
Altova MapForce 2008
138
Defining User-defined functions
Inline vs. Standard user-defined functions
8.1
Inline vs. Standard user-defined functions
The main difference between these two types of functions is the level of complexity that they
each support, and the implementation of each during code generation.
The graphical representation of the two types also differ:
 Standard user-defined functions are shown with a solid outline
 Inline user-defined functions are shown with a dashed outline
Inline user-defined functions support:
 Complex input and output components i.e. XML schema nodes
 Multiple output components within a function
 Direct connection of filters to input components
 Exists-type functions on input component e.g. exists, not-exists, substitute-missing
Inline user-defined functions do not support:
 The setting of a priority context on a parameter
 Recursive calls to an inline user-defined function
Code generation:
In essence an inline user-defined component implements the constituent components
of the user-defined function instead of generating a function call. All parameters are
evaluated and purged.
If the user-defined function is defined as inlined, filters and exists-like functions can be
used because MapForce generates code that works exactly as the function's
constituent components.
Altova MapForce 2008
© 2008 Altova GmbH
Defining User-defined functions
Inline vs. Standard user-defined functions
139
Standard user-defined function support:
 Only simple input components without hierarchies
 Only a single output component
 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 Standard user-defined functions do not support complex input and output
components, they can be created in this type of function. An error message appears when you
try to preview the result of the mapping, and prompts if you want to change the current Standard
type user-defined function, into one of type "Inline".
Standard user-defined functions do not support:
 Complex input and output components i.e. XML schema nodes
 Direct connection of filters to input components
 Exists-type functions on input components:
- Exists
- Not-exists
- Substitute-missing
Code generation:
A standard user-defined component generates code for a function call, where inputs
and outputs are passed as parameters. At runtime, the input parameter values are
evaluated first, then the function is called for each occurrence of the input data.
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 radio button of the
type you want to change it to, Standard or Inline.
Please note:
If the user-defined function was originally of type "standard" with a priority context, and was
subsequently changed to one of type "inline", then the priority context is hidden and deactivated.
Changing the same function back to "standard", shows the priority context and enables it once
again.
User-defined functions and Copy-all connections
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. Please see "Complex output components defining" for an example.
© 2008 Altova GmbH
Altova MapForce 2008
140
Defining User-defined functions
8.2
Standard user-defined function
Standard user-defined function
This example is provided as the lookup-standard.mfd file available in the C:\Documents and
Settings\<username>\My Documents\Altova\MapForce2008\MapForceExamples folder.
Aim:
To create a generic look-up function that:
 supplies Articles/Number data from the Articles XML file, to be compared to Article
numbers of a different XML file, ShortPO in this case.



Insert the ShortPO.xsd and assign ShortPO.xml as the source XML file.
Insert the CompletePO.xsd schema file, and select CompletePO as the root element.
Insert a new user-defined function using the method described below.
To create a user defined function from scratch:
1. Select the menu option Function | Create User-defined function.
2. Enter the name of the function e.g. LookupArticle.
3. Select the "Standard function" radio button and click OK to confirm
A tab only containing only one item, an output function, is displayed.
Altova MapForce 2008
© 2008 Altova GmbH
Defining User-defined functions
Standard user-defined function
141
This is the working area used to define the user-defined function.
A new library has been created in the Libraries pane with the name "user" and the
function name "LookupArticle".
3. Click the Insert Schema/XML file icon
to insert the Articles schema and select
the XML file of the same name to act as the data source.
4. Click the Insert input component icon
to insert an input component.
5. Enter the name of the input parameter, ArticleNr in this case, and click OK.
This component acts as a data input to the user-defined function and supplies the input
icon of the user-defined function.
6. Insert an "equal" component by dragging it from the core library/logical functions group.
7. Insert a filter component by clicking the Insert Filter icon
© 2008 Altova GmbH
in the toolbar.
Altova MapForce 2008
142
Defining User-defined functions
Standard user-defined function
Use the diagram below as an aid to creating the mappings in the user-defined function,
please take note of the following:
8 Right click the a parameter and select Priority context from the pop up menu.
9. Double click the output function and enter the name of the output parameter, in this
case "Name".
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 datatype of the input parameter, as well as define if the function is to have
an input icon (Connection required) in this dialog.




The user-defined function:
has one input function, ArticleNr, which receives data from the ShortPO XML file.
compares the ShortPO ArticleNr, with the Article/Number from the Articles input 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 forwards the Article Name records to the
CompletePO XML file.
10. Click the Home icon
to return to the mapping.
The LookupArticle user-defined function, is now available under the user library.
Altova MapForce 2008
© 2008 Altova GmbH
Defining User-defined functions
Standard user-defined function
143
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 mappings displayed in the graphic below and click the Output tab to see the
result of the mapping.
Please note:
Using filters in user-defined functions only make sense if the source-component is also
in the same user-defined function.
Filters can only be used to supply data into a user-defined function using input
components, if you have defined it as an inline function.
© 2008 Altova GmbH
Altova MapForce 2008
144
Defining User-defined functions
Complex user-defined function - XML node as input
8.3
Complex user-defined function - XML node as input
This example is provided as the lookup-udf-in.mfd file available in the C:\Documents and
Settings\<username>\My Documents\Altova\MapForce2008\MapForceExamples folder.
What this section will show, is how to define an inline user-defined function that contains a
complex input components.
Note that the user-defined function "FindArticle" consists of two halves.
A left half which contains the input parameters:
 a simple input parameter POArtNr
 a complex input component Articles, with mappings directly to its XML child nodes
A right half which contains:
 a simple output parameter called "Name".
The screenshot below shows the constituent components of the user-defined function, the two
input components at left and the output component at right.
Altova MapForce 2008
© 2008 Altova GmbH
Defining User-defined functions
8.3.1
Complex user-defined function - XML node as input
145
Complex input components - defining
Defining complex input components:
1. Create a user-defined function in the usual manner, i.e. Function | Create
User-Defined function and click Enter to confirm. Note that the Inline... option is
automatically selected.
2. Click the Insert input component icon
in the icon bar.
3. Enter the name of the component into the Name field.
4. Click the Complex type radio button, then click the "Choose" button next to the
Structure field.
This opens the "Insert Input Parameter" dialog box.
The top list box displays the existing components in the mapping, in this example three
schemas. Note that this list contains all of the components that have been inserted into
the active mapping: e.g. XML schema file.
The lower list box allows you to select a new complex data structure i.e. XML Schema
file.
5. Click "Insert new structure... " radio button, select the XML Schema structure entry, and
click OK to continue.
© 2008 Altova GmbH
Altova MapForce 2008
146
Defining User-defined functions
Complex user-defined function - XML node as input
6. Select the Articles.xsd from the "Open" dialog box.
7. Click the element that you would like to become the root element in the component, e.g.
Articles, and click OK to confirm.
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.
Altova MapForce 2008
© 2008 Altova GmbH
Defining User-defined functions
Complex user-defined function - XML node as input
147
8. Insert the rest of the components as shown in the screenshot below, namely: a second
"simple" input component, filter, equal and output components, and connect them as
shown.
Please note:
 The Articles input component receives its data from outside of the user-defined
function. Input icons that allow mapping to this component, are available there.
 An XML instance file to provide data from within the user-defined function, cannot be
assigned to a complex input component.
 The other input component input(1), supplies the ShortPO article number data to which
the Articles | Number is compared.
 The filter component filters out the records where both numbers are identical, and
passes them on to the output component.
10. Click the Home icon
to return to the mapping.
11. Drag the newly created user-defined component from the Libraries pane into the
mapping.
12. Create the connections as shown in the screenshot below.
© 2008 Altova GmbH
Altova MapForce 2008
148
Defining User-defined functions
Complex user-defined function - XML node as input
The left half contains the input parameters to which items from two schema/xml files are
mapped:
 ShortPO supplies the data for the input component POArtNr
 Articles supplies the data for the complex input component. The Articles.xml instance
file was assigned to the Articles schema file when the component was inserted.
 The complex input component Articles with its XML child nodes, to which data has
been mapped from the Articles component.
The right half contains:
 a simple output parameter called "Name", which passes on the filtered line items which
have the same Article number, to the Name item of Complete PO.
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.
Altova MapForce 2008
© 2008 Altova GmbH
Defining User-defined functions
8.4
Complex user-defined function - XML node as output
149
Complex user-defined function - XML node as output
This example is provided as the lookup-udf-out.mfd file available in the C:\Documents and
Settings\<username>\My Documents\Altova\MapForce2008\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
component at left and the complex output component at right.
© 2008 Altova GmbH
Altova MapForce 2008
150
Defining User-defined functions
Complex user-defined function - XML node as output
8.4.1
Complex output components - defining
Defining complex output components:
1. Create a user-defined function in the usual manner, i.e. Function | Create
User-Defined function and click Enter to confirm. Note that the Inline... option is
automatically selected.
2. Click the Insert output icon
in the icon bar, and enter a name e.g. CompletePO.
3. Click the Complex type radio button, then click the "Choose" button.
This opens the "Insert Input Parameter" dialog box.
The top list box displays the existing components in the mapping, in this example three
schemas. Note that this list contains all of the components that have been inserted into
the active mapping: e.g. XML Schema file.
The lower list box allows you to select a new complex data structure i.e. XML Schema
file.
Altova MapForce 2008
© 2008 Altova GmbH
Defining User-defined functions
Complex user-defined function - XML node as output
151
4. Click "Insert new structure... " radio button, select the XML Schema structure entry,
and click OK to continue.
5. Select the CompletePO.xsd from the "Open" dialog box.
6. Click the element that you would like to become the root element in the component,
e.g. Article, and click OK to confirm.
The CompletePO component is inserted into the user-defined function. Please note the
output icon
to the left of the component name. This shows that the component is
used as a complex output component.
© 2008 Altova GmbH
Altova MapForce 2008
152
Defining User-defined functions
Complex user-defined function - XML node as output
7. Insert the Articles schema/XML file into the user-defined function and assign the
Articles.xml as the XML instance.
8. Insert the rest of the components as shown in the screenshot below, namely: two
"simple" input components, filter, equal and multiply components, and connect them as
shown.
Please note:
 The Articles component receives its data from the Articles.xml instance file, within the
user-defined function.
 The input components supply the POArtNr (article number) and Amount data to which
the Articles | Number & Price are compared.
 The filter component filters out the records where both numbers are identical, and
passes them on to the CompletePO output component.
9. Click the Home icon
to return to the mapping.
10. Drag the newly created user-defined component from the Libraries pane into the
mapping.
11. Create the connections as shown in the screenshot below.
Altova MapForce 2008
© 2008 Altova GmbH
Defining User-defined functions
Complex user-defined function - XML node as output
153
Having created the Article connector, right click it and select "Copy-all" from the context
menu. The rest of the connectors are automatically generated, and are highlighted in
the screenshot below.
Please note:
When creating Copy-all connections between a schema and a user-defined function of type
"Inline", the two components must be based on the same schema! It is not necessary that they
both have the same root elements however.
The left half contains the input parameter to which a single item is mapped:
 ShortPO supplies the article number to the POArtNr input component.
The right half contains:
 a complex output component called "Article (CompletePO)" with its XML child nodes,
which maps the filtered items, of the same Article number, to CompletePO.
© 2008 Altova GmbH
Altova MapForce 2008
154
Defining User-defined functions
8.5
User-defined function - example
User-defined function - example
The PersonByListBranchOffice.mfd file available in the C:\Documents and
Settings\<username>\My Documents\Altova\MapForce2008\MapForceExamples folder,
describes the following features in greater detail:




Nested User-defined functions e.g. LookupPerson
Look-up functions that generate a string output e.g. LookupPerson
Optional input-parameters which can also supply a default value e.g. the EqualAnd
component (contained in the LookupPerson component)
Configurable input parameters, which can also double as a command line parameter(s)
when executing the generated mapping code!
Altova MapForce 2008
© 2008 Altova GmbH
Defining User-defined functions
User-defined function - example
155
Configurable input parameters
The input (1) component 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 MapForce Engine to preview the data in the Output
window.
To define the Input value:
1. Double click the input (1), component and enter a different value in the "Value" text box
of the Preview Mode group e.g. "Nanonull Partners, Inc.", and click OK to confirm.
2. Click the Output tab to see the effect.
A different set of persons are now displayed.
Please note that the data entered here is only used in "preview" mode i.e. when clicking
the Output tab. If a value is not entered, or the check box is deactivated, then the data
mapped to the input icon "default" is used.
Please see Input values, overrides and command line parameters for more information.
© 2008 Altova GmbH
Altova MapForce 2008
156
Defining User-defined functions
User-defined function - example
LookupPerson component
Double clicking this user-defined component displays its constituent components shown below.
What this component does is:



Compares the Office, First, and Last names of BranchOffices.xml, with the same fields of
the Altova_Hierarchical.xml file, using the input components and the EqualAnd
user-defined components.
Combines the Email, PhoneExt and Title items using the Person2Details user-defined
function
Passes on the combined person data to the output component if the previous EqualAnd
comparisons are all true (i.e. supplied "true" to the filter component).
A user-defined function always outputs a value, which may even be an empty string! This would
be the case if the filter component bool value is false. Only an empty string would be output
instead of data supplied by the Person2Details component.



The three input components, input (1) to input (3), receive their data from the
BranchOffices.xml file.
The EqualAnd component compares two values and provides an optional comparison
value, as well as a default value.
Person2Details combines three person fields and passes on the result to the filter
component.
Altova MapForce 2008
© 2008 Altova GmbH
Defining User-defined functions
User-defined function - example
157
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, Input (3)
Pass on the boolean value of this comparison to the output parameter.
Optional parameters
Double clicking the "input (3)" parameter, of the EqualAnd user-defined function shown above,
allows you to make parameters optional, by unchecking the "Connection required" check box.
If "Connection 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".
© 2008 Altova GmbH
Altova MapForce 2008
158
Defining User-defined functions

User-defined function - example
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.
Altova MapForce 2008
© 2008 Altova GmbH
Defining User-defined functions
User-defined function - example
159
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).
© 2008 Altova GmbH
Altova MapForce 2008
Chapter 9
Adding custom XSLT and XQuery functions
162
Adding custom XSLT and XQuery functions
9
Adding custom XSLT and XQuery functions
MapForce allows you to extend the installed XSLT function libraries with your own custom
functions. This option is made available when you select XSLT as the output, by clicking the
XSLT icon, or selecting Output | XSLT 1.0.
XSLT files appear as libraries, and display all named templates as functions below the library
name.
Functions must be declared as Named Templates conforming to the XSLT 1.0
specification in the XSLT file.
 If the imported XSLT file imports, or includes other XSLT files, then these XSLT files
and functions will be imported as well.
 Each named template appears as a function below each library name.
 The amount of mappable input icons depends on the number of parameters used in the
template call; optional parameters are also supported.
 Updates to imported XSLT files occur at program start or whenever the files change.
 Namespaces are supported
Please note:
When writing named templates please make sure that the XPath statements used in
the template are bound to the correct namespace(s). The namespace bindings of the
mapping can be viewed by clicking the XSLT tab. Please see: the XSLT 1.0
implementation specific document for more information.

Altova MapForce 2008
© 2008 Altova GmbH
Adding custom XSLT and XQuery functions
9.1
Adding custom XSLT 1.0 functions
163
Adding custom XSLT 1.0 functions
The files needed for the simple example shown below, are available in the C:\Documents and
Settings\<username>\My Documents\Altova\MapForce2008\MapForceExamples directory.




Name-splitter.xslt
Name-splitter.xml (the XML instance file for Customer.xsd)
Customers.xsd
CompletePO.xsd
Please see: Aggregate functions for an additional example of using named templates to sum
nodes.
To add a custom XSLT function:
1. Create an XSLT file that achieves the transformation/result you want.
The example below, Name-splitter.xslt, shows a named template called "tokenize"
with a single parameter "string". What the template does, is work through an input string
and separate capitalized characters with a space for each occurrence.
2. Click the Add Libraries button, and then click the Add button in the following dialog
box.
© 2008 Altova GmbH
Altova MapForce 2008
164
Adding custom XSLT and XQuery functions
Adding custom XSLT 1.0 functions
3. Select the XSL, or XSLT file, that contains the named template you want to act as a
function, in this case Name-splitter.xslt. The XSLT file appears in the Libraries tab.
4. Click OK to insert the new function.
The XSLT file name appears in the library window, along with the function(s) defined as
named templates, below it. In this example Name-splitter with the tokenize function.
5. Drag the function into the Mapping window, to use it in you current mapping, and map
the necessary items, as show in the screenshot below.
Altova MapForce 2008
© 2008 Altova GmbH
Adding custom XSLT and XQuery functions
Adding custom XSLT 1.0 functions
165
6. Click the XSLT tab to see the generated XSLT code.
Please note:
As soon as a named template is used in a mapping, the XSLT file containing the
named template is included in the generated XSLT code (xsl:include href...), and is
called using the command xsl:call-template.
7. Click the Output tab to see the result of the mapping.
To delete custom XSLT functions:
1. Click the Add Libraries button.
2. Click to the specific XSLT library name in the Libraries tab
3. Click the Delete button, then click OK to confirm.
© 2008 Altova GmbH
Altova MapForce 2008
166
Adding custom XSLT and XQuery functions
9.2
Adding custom XSLT 2.0 functions
Adding custom XSLT 2.0 functions
MapForce also allows you to import XSLT 2.0 functions that occur in an XSLT 2.0 document in
the form:
<xsl:function name="MyFunction">
Please see: the XSLT 2.0 implementation specific document for more information, as well as
Aggregate functions for an additional example of using named templates to sum nodes.
Datatypes in XPath 2.0
If your XML document references an XML Schema and is valid according to it, you must
explicitly construct or cast datatypes that are not implicitly converted to the required datatype by
an operation.
In the XPath 2.0 Data Model used by the Altova XSLT 2.0 Engine, all atomized node values
from the XML document are assigned the xs:untypedAtomic datatype. The
xs:untypedAtomic type works well with implicit type conversions.
For example,



the expression xs:untypedAtomic("1") + 1 results in a value of 2 because the
xdt:untypedAtomic value is implicitly promoted to xs:double by the addition
operator.
Arithmetic operators implicitly promote operands to xs:double.
Value comparison operators promote operands to xs:string before comparing.
Altova MapForce 2008
© 2008 Altova GmbH
Adding custom XSLT and XQuery functions
9.3
Aggregate functions - summing nodes in XSLT1 and 2
167
Aggregate functions - summing nodes in XSLT1 and 2
This section describes the method you can use to process multiple nodes of an XML instance
document and have the result mapped as a single value to a target item. The files used in this
example are available in the C:\Documents and Settings\<username>\My
Documents\Altova\MapForce2008\MapForceExamples\Tutorial\ folder and consists of:
Summing-nodes.mfd
input.xml
input.xsd and output.xsd
Summing-nodes.xslt
mapping file
input XML file
source and target schema files
xslt file containing a named template to sum the
individual nodes
There are two separate methods of creating and using aggregate functions:


Using the aggregate functions available in the core library of the Library pane
Using a Named Template.
Aggregate functions - library
Depending on the XSLT library you select, XSLT 1 or XSLT 2, different aggregate functions are
available in the core library. XSLT 1 supports count and sum, while XSLT 2 supports avg, count,
max, min, string-join and sum.
Drag the aggregate function that you use from the library into the mapping area and connect the
source and target components as shown in the screenshot below.
For more information on this type of aggregate function, please also see Aggregate functions.
Aggregate function - Named template
The screenshot below shows the XML input file. The aim of the example is to sum the Price
fields of any number of products, in this case products A and B.
© 2008 Altova GmbH
Altova MapForce 2008
168
Adding custom XSLT and XQuery functions
Aggregate functions - summing nodes in XSLT1 and 2
The screenshot below shows the XSLT stylesheet which uses the named template "Total" and
a single parameter "string". What the template does, is work through the XML input file and sum
all the values obtained by the XPath expression /Product/Price, in the document.
1. Click the Add Libraries button, and select the Libraries tab of the Options dialog box.
2. Click the Add button and select the Summing-nodes.xslt file from the C:\Documents
and Settings\<username>\My
Documents\Altova\MapForce2008\MapForceExamples\Tutorial\ folder.
3. Drag in the Total function from the newly created Summing-nodes library and create the
mappings as shown below.
4. Click the Output tab to preview the mapping result.
Altova MapForce 2008
© 2008 Altova GmbH
Adding custom XSLT and XQuery functions
Aggregate functions - summing nodes in XSLT1 and 2
169
The two Price fields of both products have been added and placed into the Total field.
To sum the nodes in XSLT 2.0:
 Change the stylesheet declaration in the template to ... version="2.0".
© 2008 Altova GmbH
Altova MapForce 2008
Chapter 10
MapForce Reference
172
MapForce Reference
10
MapForce Reference
The following section lists all the menus and menu options in MapForce, and supplies a short
description of each.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce Reference
10.1
File
173
File
New
Creates a new mapping document
Open
Opens previously defined mapping (*.mfd) files.
Save
Saves the currently active mapping using the currently active file name.
Save As
Saves the currently active mapping with a different name, or allows you to supply a new name if
this is the first time you save it.
Reload
Reloads the currently active mapping file. You are asked if you want to lose your last changes.
Close
Closes the currently active mapping file. You are asked if you want to save the file before it
closes.
Close all
Closes all currently open mapping files. You are asked if you want to save any of the unsaved
mapping files.
Print
Opens the Print dialog box, from where you can printout your mapping as hardcopy.
"Use current", retains the currently defined zoom factor of the mapping. "Use optimal" scales
the mapping to fit the page size. You can also specify the zoom factor numerically. Component
scrollbars are not printed. You can also specify if you want to allow the graphics to be split over
several pages or not.
Print Preview
Opens the same Print dialog box with the same settings as described above.
Print Setup
Open the Print Setup dialog box in which you can define the printer you want to use and the
© 2008 Altova GmbH
Altova MapForce 2008
174
MapForce Reference
File
paper settings.
Validate Mapping
Validating a Mapping validates that all mappings (connectors) are valid and displays any
warnings or errors.
Please see "Validating mappings" for more information
Generate code in selected language
Generates code in the currently selected language of your mapping. The currently selected
language is visible as a highlighted programming language icon in the toolbar: XSLT, XSLT 2.
Generate code in | XSLT (XSLT2)
This command generates the XSLT file(s) needed for the transformation from the source file(s).
Selecting this option opens the Browse for Folder dialog box where you select the location of
the XSLT file.
Note: the name of the generated XSLT file(s) is defined in the Application Name field of the
Mapping Output dialog box. This dialog is opened by selecting File | Mapping Settings menu
option.
Mapping settings
The document-specific settings are defined here. They are stored in the *.mfd file.
Mapping Output
Application Name: defines the XSLT1.0/2.0 file name prefix for the generated transformation
files.
Recent files
Displays a list of the most recently opened files. You can also use the hotkeys ALT+F+F+1
(from 1-9) to open a file.
Recent projects
Displays a list of the most recently opened projects. You can also use the hotkeys ALT+F+T+1
(from 1-9) to open a project.
Exit
Exits the application. You are asked if you want to save any unsaved files.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce Reference
10.2
Edit
175
Edit
Most of the commands in this menu, become active when you view the result of a mapping in
the Output tab, or preview XSLT code in the XSLT tab.
Undo
MapForce has an unlimited number of "Undo" steps that you can use to retrace you mapping
steps.
Redo
The redo command allows you to redo previously undone commands. You can step backward
and forward through the undo history using both these commands.
Find
Allows you to search for specific text in either the XSLT, XSLT2 or Output tab.
Find Next
F3
Searches for the next occurrence of the same search string.
Cut/Copy/Paste/Delete
The standard windows Edit commands, allow you to cut, copy etc., any components or
functions visible in the mapping window.
Select all
Selects all components in the Mapping tab, or the text/code in the XSLT, XSLT2, or Output tab.
© 2008 Altova GmbH
Altova MapForce 2008
176
MapForce Reference
10.3
Insert
Insert
XML Schema / File
Inserts an XML schema file into the mapping tab as data source or target component. You can
select XML files with a schema reference, in this case the referenced schema is automatically
inserted. If you select an XML schema file, you are prompted if you want to include an XML
instance file which supplies the data for the XSLT, XSLT2, , and Output previews. If you select
an XML file without a schema reference, you are prompted if you want to generate a matching
XML schema automatically.
Constant
Inserts a constant which is a function component that supplies fixed data to an input icon. The
data is entered into a dialog box when creating the component. There is only one output icon on
a constant function. You can select the following types of data: String, Number and All other.
Filter: Nodes/Rows
Inserts a component that uses two input and output parameters: node/row and bool, and
on-true, on-false. If the Boolean is true, then the value of the node/row parameter is forwarded
to the on-true parameter. If the Boolean is false, then the complement value is passed on to the
on-false parameter. Please see the tutorial example on how to use a filter.
Value-Map
Inserts a component that transforms an input value to an output value using a lookup table. The
component only has one input and output item. Please see Value-Map - transforming input data
for more information.
IF-Else Condition
A condition is a component which allows you to pass on different sets of data depending on the
outcome of a preset condition. The component header displays the text "if-else".
 The first input parameter is a bool, which contains the data you are checking against.
 The value-true input parameter supplies the data to be passed on, as a result, if the
condition is true.
 The value-false supplies the data to be passed on if the condition is false.
 The result parameter outputs the data supplied by the value-true/false input
parameters.
Exception
The exception component allows you to interrupt a mapping process when a specific condition
is met. Please see MapForce Exceptions, for more information.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce Reference
10.4
Component
177
Component
Align tree left
Aligns all the items along the left hand window border.
Align tree right
Aligns all the items along the right hand window border. This display is useful when creating
mappings to the target schema.
Change Root element
Allows you to change the root element of the XML instance document. Useful in the target
schema window, as this limits or preselects the schema data.
Edit Schema Definition in XMLSpy
Selecting this option, having previously clicked an XML-Schema/document, opens the XML
Schema file in the Schema view of XMLSpy where you can edit it.
Duplicate input
Inserts a copy/clone of the selected item, allowing you to map multiple input data to this item.
Duplicate items do not have output icons, you cannot use them as data sources. Please see
the Duplicating input items section in the tutorial for an example of this.
Remove duplicate
Removes a previously defined duplicate item. Please see the Duplicating input items section in
the tutorial for more information.
Component Settings
Opens a dialog box which displays the currently selected component settings. If the component
is an XML-Schema file then the Component Settings dialog box is opened. If the component is
a Text file, then the "Text import / export" dialog box is opened.
© 2008 Altova GmbH
Altova MapForce 2008
178
MapForce Reference
Component
Schema file: Shows the file name and path of the target schema.
Input XML-Instance: Allows you to select, or change the XML-Instance for the currently
selected schema component. This field is filled when you first insert the schema
component and assign an XML-instance file.
Output XML-Instance for code generation: This is file name and path where the XML target
instance is placed, when generating and executing program code.
The entry from the Input XML-Instance field, is automatically copied to this field when
you assign the XML-instance file. If you do not assign an XML-Instance file to the
component, then this field contains the entry schemafilenameandpath.xml.
Prefix for target namespace: Allows you to enter a prefix for the Target Namespace if this is a
schema / XML document. A Target namespace has to be defined in the target schema,
for the prefix to be assigned here.
Add schema location: Adds the absolute path of the referenced XML Schema file to the root
element of the XML output.
Deactivating this option allows you to decouple the XML instance from the referenced
XML Schema or DTD. Use this option if you want to send the resulting XML output to
someone who does not have access to the underlying XML Schema.
Pretty-print output: Reformats your XML document in the Output pane to give a structured
display of the document. Each child node is offset from its parent by a single tab
character. )
Encoding settings
Altova MapForce 2008
© 2008 Altova GmbH
MapForce Reference
Component
179
From MapForce 2008 each component, source, as well as target, has its own encoding
settings. This means that the *.mfd mapping files do not have a default encoding, each
component that makes up the mapping file has its own. Components in this general sense are
all XML, and Text components.
There is however a default encoding setting defined in the Tools | Options General tab, called
"Default encoding for new components" which is applied whenever new components are
created/inserted. When mappings from previous versions are opened, the default encoding
setting will be used.
The encoding control group consists of 3 controls:



Encoding name selection combobox.
Byte order selection combobox (little endian, big endian).
Include Byte Order Mark checkbox.
Default settings are:
 UTF-8
 little endian (disabled for UTF-8)
 no Byte Order Mark.
© 2008 Altova GmbH
Altova MapForce 2008
180
MapForce Reference
10.5
Connection
Connection
Auto Connect Matching Children
Activates or de-activates the "Auto connect child items" function, as well as the icon in the icon
bar.
Settings for Connect Matching Children
Opens the Connect Matching Children dialog box in which you define the connection settings.
Connect Matching Children
This command allows you to create multiple connectors for items of the same name, in both
the source and target schemas. The settings you define in this dialog box are retained, and are
applied when connecting two items, if the "Auto connect child items" icon
in the title bar is
active. Clicking the icon, switches between an active and inactive state. Please see the section
on Connector properties for further information.
Target Driven (Standard)
Changes the connector type to Standard mapping, please see: "Source-driven / mixed content
vs. standard mapping" for more information.
Copy-all
Creates connectors for all matching child items, where each of the child connectors are
displayed as a subtree of the parent connector, please see "Copy-all connections" for more
information.
Source Driven (mixed content)
Changes the connector type to source driven / mixed content, and enables the selection of
additional elements to be mapped. The additional elements have to be child items of the
mapped item in the XML source file, to be able to be mapped. Please see Default settings:
mapping mixed content for more information.
Connection settings:
Opens the Connection Settings dialog box in which you can define the specific (mixed content)
settings of the current connector. Note that unavailable options are greyed out.
Please note that these settings also apply to complexType items which do not have any text
nodes!
Altova MapForce 2008
© 2008 Altova GmbH
MapForce Reference
Connection
181
Annotation settings:
Individual connectors can be labeled for clarity.
1. Double click a connector and enter the name of the connector in the Description field.
This enables all the options in the Annotation Settings group.
2. Use the remaining groups to define the position and alignment of the label.
© 2008 Altova GmbH
Altova MapForce 2008
182
MapForce Reference
10.6
Function
Function
Create user-defined function:
Creates a new user-defined function. Selecting this option creates and empty user-defined
function, into which you insert the components you need. Please note that a single output
function is automatically inserted when you define such a function, and that only one output
component can be present in a user-defined function. Please see "Creating a user-defined
function from scratch" for more information.
Create user-defined function based on selection:
Creates a new user-defined function based on the currently selected elements in the mapping
window. Please see "Adding user-defined functions" for more information.
Function settings:
Opens the settings dialog box of the currently active user-defined function allowing you to
change the current settings. Use this method to change the user-defined function type, i.e.
double click the title bar of a user-defined function to see its contents, then select this menu
option to change its type.
Insert Input:
Inserts an "input" component into the mapping, or into a user-defined function.
If you are working in the main Mapping tab, the dialog box shown below is displayed. This type
of input component allows you to:


define an override value for the data that is being input by the current mapping input,
and
use this input component as a parameter in the command line execution of the
compiled mapping.
Please see "Input values, overrides and command line parameters" for more
information.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce Reference
Function
183
If you are working in a user-defined function tab, the dialog box shown below is displayed. This
type of input component allows you to define:


simple inputs, if this is a Standard user-defined function
complex inputs, e.g. schema structures, if this is an Inline user-defined function.
Insert Output
Inserts an "Output" component into a user-defined function. In a user-defined function tab, the
dialog box shown below is displayed. This type of input component allows you to define:


simple outputs, if this is a Standard user-defined function
complex outputs, e.g. schema structures, if this is an Inline user-defined function.
© 2008 Altova GmbH
Altova MapForce 2008
184
MapForce Reference
10.7
Output
Output
The XSLT, XSLT2 options allow you to define the target language you want your code to be in.
Note that the MapForce engine presents a preview of the mapping result, when you click the
Output tab. .
Validate Output XML file
Validates the resultant XML file against the referenced schema.
Save Output XML File
Saves the currently visible data in the Output tab.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce Reference
10.8
View
185
View
Show Annotations
Displays XML schema annotations in the component window.
If the Show Types icon is also active, then both sets of info are show in grid form
Show Types
Displays the schema datatypes for each element or attribute.
If the Show Annotations icon is also active, then both sets of info are show in grid form.
Show library in function header
Displays the library name in parenthesis in the function title.
Show Tips
Displays a tooltip containing explanatory text when the mouse pointer is placed over a function.
Show selected component connectors
Switches between showing:


all mapping connectors, or
those connectors relating to the currently selected components.
Show connectors from source to target
Switches between showing:


connectors that are directly connected to the currently selected component, or
connectors linked to the currently selected component, originating from source and
terminating at the target components.
Zoom
Opens the Zoom dialog box. You can enter the zoom factor numerically, or drag the slider to
change the zoom factor interactively.
Status Bar
Switches the Status Bar, visible below the Messages window, on or off.
Library Window
Switches the Library window, containing all library functions, on or off.
Messages
Switches the Validation output window on, or off. When generating code the Messages output
window is automatically activated to show the validation result.
Overview
Switches the Overview window on, or off. Drag the rectangle to navigate your Mapping view.
© 2008 Altova GmbH
Altova MapForce 2008
186
MapForce Reference
10.9
Tools
Tools
Customize
The customize command lets you customize MapForce to suit your personal needs.
The Keyboard tab allows you to define (or change) keyboard shortcuts for any MapForce
command.
To assign a new Shortcut to a command:
1. Select the Tools | Customize command and click the Keyboard tab.
2. Click the Category combo box to select the menu name.
3. Select the command you want to assign a new shortcut to, in the Commands list box
4. Click in the Press New Shortcut Key: text box, and press the shortcut keys that are to
activate the command.
The shortcuts appear immediately in the text box. If the shortcut was assigned
previously, then that function is displayed below the text box.
5. Click the Assign button to assign the shortcut.
The shortcut now appears in the Current Keys list box.
(To clear the entry in the Press New Shrotcut Key text box, press any of the control
keys, CTRL, ALT or SHIFT).
To de-assign or delete a shortcut:
1. Click the shortcut you want to delete in the Current Keys list box.
2. Click the Remove button.
3. Click the Close button to confirm.
Set accelerator for:
Currently no function.
Currently assigned keyboard shortcuts:
Hotkeys by key
F1
Altova MapForce 2008
Help Menu
© 2008 Altova GmbH
MapForce Reference
Tools
F2
F3
F10
Num +
Num Num *
Next bookmark (in output window)
Find Next
Activate menu bar
Expand current item node
Collapse item node
Expand all from current item node
CTRL + TAB
CTRL + F6
CTRL + F4
Switches between open mappings
Cycle through open windows
Closes the active mapping tab
Alt + F4
Alt + F, F, 1
Alt + F, T, 1
Closes MapForce
Opens the last file
Opens the last project
CTRL + N
CTRL + O
CTRL + S
CTRL + P
File New
File Open
File Save
File Print
CTRL + A
CTRL + X
CTRL + C
CTRL + V
CTRL + Z
CTRL + Y
Select All
Cut
Copy
Paste
Undo
Redo
Del
Shift + Del
CTRL + F
F3
Delete component (with prompt)
Delete component (no prompt)
Find
Find Next
Arrow keys
(up / down)
Esc.
Return
Select next item of component
Abandon edits/close dialog box
Confirms a selection
Output window hotkeys
CTRL + F2
F2
SHIFT + F2
CTRL + SHIFT + F2
Insert Remove/Bookmark
Next Bookmark
Previous Bookmark
Remove All Bookmarks
187
Zooming hotkeys
CTRL + mouse wheel forward Zoom In
CTRL + mouse wheel back
Zoom Out
CTRL + 0 (Zero)
Reset Zoom
Options
Opens the Options dialog box through which you can:


Add or delete user defined XSLT functions.
Define general settings, such as the default character encoding for new components, in
the General tab.
© 2008 Altova GmbH
Altova MapForce 2008
188
MapForce Reference
Tools
General tab:
 Specify if you want to show the logo on start and/or when printing.
 Enable/disable the MapForce gradient background
 Define the Default Output Encoding
 an execution timeout for the Output tab when previewing the mapping result.
Libraries tab:
 Add or delete user-defined XSLT, or programming language Libraries/functions to
MapForce.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce Reference
Help Menu
189
10.10 Help Menu
The Help menu contains commands to access the onscreen help manual for MapForce,
commands to provide information about MapForce, and links to support pages on the Altova
web site. The Help menu also contains the Registration dialog, which lets you enter your license
key-code once you have purchased the product.
The description of the Help menu commands is organized into the following sub-sections:



Table of Contents, Index, Search
Registration, Order Form
Other Commands
© 2008 Altova GmbH
Altova MapForce 2008
190
MapForce Reference
Help Menu
10.10.1 Table of Contents, Index, Search
The Table of Contents command opens the onscreen help manual for MapForce with the
Table of Contents displayed in the left-hand-side pane of the Help window. The Table of
Contents provides a good overview of the entire Help document. Clicking an entry in the Table
of Contents takes you to that topic.
The Index command opens the onscreen help manual for MapForce with the Keyword Index
displayed in the left-hand-side pane of the Help window. The index lists keywords and lets you
navigate to a topic by double-clicking the keyword. If a keyword is linked to more than one topic,
you are presented with a list of the topics to choose from.
The Search command opens the onscreen help manual for MapForce with the Search dialog
displayed in the left-hand-side pane of the Help window. To search for a term, enter the term in
the input field, and press Return. The Help system performs a full-text search on the entire Help
documentation and returns a list of hits. Double-click any item to display that item.
Altova MapForce 2008
© 2008 Altova GmbH
MapForce Reference
Help Menu
191
10.10.2 Activation, Order Form, Registration, Updates
Software Activation
After you download your Altova product software, you can activate it using either a free
evaluation key or a purchased permanent license key.


Note:
Free evaluation key. When you first start the software after downloading and installing
it, the Software Activation dialog will pop up. In it is a button to request a free evaluation
key-code. Enter your name, company, and e-mail address in the dialog that appears,
and click Request Now! The evaluation key is sent to the e-mail address you entered
and should reach you in a few minutes. Now enter the key in the key-code field of the
Software Activation dialog box and click OK to start working with your Altova product.
The software will be unlocked for a period of 30 days.
Permanent license key. The Software Activation dialog contains a button to purchase
a permanent license key. Clicking this button takes you to Altova's online shop, where
you can purchase a permanent license key for your product. There are two types of
permanent license: single-user and multi-user. Both will be sent to you by e-mail. A
single-user license contains your license-data and includes your name, company,
e-mail, and key-code.A multi-user license contains your license-data and includes your
company name and key-code. Note that your license agreement does not allow you to
install more than the licensed number of copies of your Altova software on the
computers in your organization (per-seat license). Please make sure that you enter the
data required in the registration dialog exactly as given in your license e-mail.
When you enter your license information in the Software Activation dialog, ensure that
you enter the data exactly as given in your license e-mail. For multi-user licenses, each
user should enter his or her own name in the Name field.
The Software Activation dialog can be accessed at any time by clicking the Help | Software
Activation command.
Order Form
When you are ready to order a licensed version of MapForce, you can use either the Order
license key button in the Software Activation dialog (see previous section) or the Help | Order
Form command to proceed to the secure Altova Online Shop.
Registration
The first time you start your Altova software after having activated it, a dialog appears asking
whether you would like to register your product. There are three buttons in this dialog:



OK: Takes you to the Registration Form
Remind Me Later: Pops up a dialog in which you can select when you wish to be next
reminded.
Cancel: Closes the dialog and suppresses it in future. If you wish to register at a later
time, you can use the Help | Registration command.
Check for Updates
Checks with the Altova server whether a newer version than yours is currently available and
displays a message accordingly
© 2008 Altova GmbH
Altova MapForce 2008
192
MapForce Reference
Help Menu
10.10.3 Other Commands
The Support Center command is a link to the Altova Support Center on the Internet. The
Support Center provides FAQs, discussion forums where problems are discussed, and access
to Altova's technical support staff.
The FAQ on the Web command is a link to Altova's FAQ database on the Internet. The FAQ
database is constantly updated as Altova support staff encounter new issues raised by
customers.
The Components Download command is a link to Altova's Component Download Center on
the Internet. From here you will be able to download a variety of companion software to use with
Altova products. Such software ranges from XSLT and XSL-FO processors to Application
Server Platforms. The software available at the Component Download Center is typically free of
charge.
The MapForce on the Internet command is a link to the Altova website on the Internet. You
can learn more about MapForce and related technologies and products at the Altova website.
The MapForce Training command is a link to the Online Training page at the Altova website.
Here you can select from online courses conducted by Altova's expert trainers.
The About MapForce command displays the splash window and version number of your
product.
Altova MapForce 2008
© 2008 Altova GmbH
Chapter 11
The MapForce API
194
The MapForce API
11
The MapForce API
The COM-based API of MapForce enables clients to easily access the functionality of
MapForce. As a result, it is now possible to automate a wide range of tasks.
MapForce follows the common specifications for automation servers set out by Microsoft. It is
possible to access the methods and properties of the MapForce API from common
development environments, such as those using C, C++ and VisualBasic, and with scripting
languages like JavaScript and VBScript.
The following guidelines should be considered in your client code:




Do not hold references to objects in memory longer than you need them. If a user
interacts between two calls of your client, then there is no guarantee that these
references are still valid.
Be aware that if your client code crashes, instances of MapForce may still remain in the
system.
See Error handling for details of how to avoid annoying error messages.
Free references explicitly, if using languages such as C or C++.
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
11.1
Overview
195
Overview
This overview of the MapForce API provides you with the object model for the API and a
description of the most important API concepts. The following topics are covered:




The object model
Example: Code-Generation
Example: Project Support
Error handling
© 2008 Altova GmbH
Altova MapForce 2008
196
The MapForce API
Overview
11.1.1 Object model
The starting point for every application which uses the MapForce API is the Application
object.
To create an instance of the Application object, call
CreateObject("MapForce.Application") from VisualBasic, or a similar function from
your preferred development environment, to create a COM object. There is no need to create
any other objects to use the complete MapForce API. All other interfaces are accessed through
other objects, with the Application object as the starting point.
The application object consists of the following parts (each indentation level indicates a child–parent
relationship with the level directly above):
Application
Options
Project
ProjectItem
Documents
Document
MapForceView
ErrorMarkers
ErrorMarker
Once you have created an Application object, you can start using the functionality of
MapForce. You will generally either open an existing Document, create a new one, or generate
code for or from this document.
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
Overview
197
11.1.2 Example: Code-Generation
See also
Code Generation
The following JScript example shows how to load an existing document and generate different
kinds of mapping code for it.
// ------------------- begin JScript example --------------------// Generate Code for existing mapping.
// works with Windows scripting host.
// ----------------- helper function -----------------function Exit(strErrorText)
{
WScript.Echo(strErrorText);
WScript.Quit(-1);
}
function ERROR(strText, objErr)
{
if (objErr != null)
Exit ("ERROR: (" + (objErr.number & 0xffff) + ")" +
objErr.description + " - " + strText);
else
Exit ("ERROR: " + strText);
}
// --------------------------------------------------// ----------------- MAIN -----------------// ----- create the Shell and FileSystemObject of the windows scripting
try
{
objWshShell = WScript.CreateObject("WScript.Shell");
objFSO = WScript.CreateObject("Scripting.FileSystemObject");
}
catch(err)
{ Exit("Can't create WScript.Shell object"); }
// ----- open MapForce or access running instance and make it visible
try
{
objMapForce = WScript.GetObject ("", "MapForce.Application");
// remove this line to perform
objMapForce.Visible = true;
background processing
}
catch(err) { WScript.Echo ("Can't access or create MapForce.Application"); }
// ----- open an existing mapping. adapt this to your needs!
objMapForce.OpenDocument(objFSO.GetAbsolutePathName ("Test.mfd"));
// ----- access the mapping to have access to the code generation methods
var objDoc = objMapForce.ActiveDocument;
// ----- set the code generation output properties and call the code
generation methods.
// ----- adapt the output directories to your needs
try
{
// ----- code generation uses some of these options
var objOptions = objMapForce.Options;
© 2008 Altova GmbH
Altova MapForce 2008
198
The MapForce API
Overview
// ----- generate XSLT ----objOptions.XSLTDefaultOutputDirectory = "C:\\test\\TestCOMServer\\XSLT"
;
objDoc.GenerateXSLT();
// ----- generate Java Code ----objOptions.CodeDefaultOutputDirectory = "C:\\test\\TestCOMServer\\Java"
;
objDoc.GenerateJavaCode();
// ----- generate CPP Code, use same cpp code options as the last time
----objOptions.CodeDefaultOutputDirectory = "C:\\test\\TestCOMServer\\CPP";
objDoc.GenerateCppCode();
// ----- generate C# Code, use options C# code options as the last time
----objOptions.CodeDefaultOutputDirectory =
"C:\\test\\TestCOMServer\\CHash";
objDoc.GenerateCHashCode();
}
catch (err)
{ ERROR ("while generating XSL or program code", err); }
// hide MapForce to allow it to shut down
objMapForce.Visible = false;
// -------------------- end example ---------------------
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
Overview
199
11.1.3 Example: Project Support
See also
Code Generation
The following JScript example shows how you can use the MapForce project and project-item
objects of the MapForce API to automated complex tasks. Depending on your installation you
might need to change the value of the variable strSamplePath to the example folder of your
MapForce installation.
To successfully run all operations in this example below, you will need the Enterprise version of
MapForce. If you have the Professional version running, you should comment out the lines that
insert the WebService project. Users of the Standard edition will not have access to
project-related functions at all.
// //////////// global variables /////////////////
var objMapForce = null;
var objWshShell = null;
var objFSO = null;
// !!! adapt the following path to your needs. !!!
var strSamplePath = "C:\\Documents and Settings\\<username>\\My
Documents\\Altova\\MapForce2008\\MapForceExamples\\Tutorial\\";
// /////////////////////// Helpers //////////////////////////////
function Exit(strErrorText)
{
WScript.Echo(strErrorText);
WScript.Quit(-1);
}
function ERROR(strText, objErr)
{
if (objErr != null)
Exit ("ERROR: (" + (objErr.number & 0xffff) + ")" +
objErr.description + " - " + strText);
else
Exit ("ERROR: " + strText);
}
function CreateGlobalObjects ()
{
// the Shell and FileSystemObject of the windows scripting host often
always useful
try
{
objWshShell = WScript.CreateObject("WScript.Shell");
objFSO = WScript.CreateObject("Scripting.FileSystemObject");
}
catch(err)
{ Exit("Can't create WScript.Shell object"); }
// create the MapForce connection
// if there is a running instance of MapForce (that never had a
connection) - use it
// otherwise, we automatically create a new instance
try
{
objMapForce = WScript.GetObject("", "MapForce.Application");
}
catch(err)
{
© 2008 Altova GmbH
Altova MapForce 2008
200
The MapForce API
Overview
{ Exit("Can't access or create MapForce.Application"); }
}
}
// ---------------------------------------------------------// print project tree items and their properties recursively.
// ---------------------------------------------------------function PrintProjectTree( objProjectItemIter, strTab )
{
while ( ! objProjectItemIter.atEnd() )
{
// get current project item
objItem = objProjectItemIter.item();
try
{
// ----- print common properties
strGlobalText += strTab + "[" + objItem.Kind + "]" +
objItem.Name + "\n";
// ----- print code generation properties, if available
try
{
if ( objItem.CodeGenSettings_UseDefault )
strGlobalText += strTab + " Use default
code generation settings\n";
else
strGlobalText += strTab + " code generation
language is " +
objItem.CodeGenSettings_Language +
" output folder is " +
objItem.CodeGenSettings_OutputFolder + "\n";
}
catch( err ) {}
// ----- print WSDL settings, if available
try
{
strGlobalText += strTab + " WSDL File is " +
objItem.WSDLFile +
" Qualified Name is " +
objItem.QualifiedName + "\n";
}
catch( err ) {}
}
catch( ex )
{ strGlobalText += strTab + "[" + objItem.Kind + "]\n" }
// ---- recurse
PrintProjectTree( new Enumerator( objItem ), strTab + '
' );
objProjectItemIter.moveNext();
}
}
// ---------------------------------------------------------// Load example project installed with MapForce.
// ---------------------------------------------------------function LoadSampleProject()
{
// close open project
objProject = objMapForce.ActiveProject;
if ( objProject != null )
objProject.Close();
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
Overview
201
// open sample project and iterate through it.
// sump properties of all project items
objProject = objMapForce.OpenProject(strSamplePath +
"MapForceExamples.mfp");
strGlobalText = '';
PrintProjectTree( new Enumerator (objProject), ' ' )
WScript.Echo( strGlobalText );
objProject.Close();
}
// ---------------------------------------------------------// Create a new project with some folders, mappings and a
// Web service project.
// ---------------------------------------------------------function CreateNewProject()
{
try
{
// create new project and specify file to store it.
objProject = objMapForce.NewProject(strSamplePath + "Sample.mfp"
);
// create a simple folder structure
objProject.CreateFolder( "New Folder 1");
objFolder1 = objProject.Item(0);
objFolder1.CreateFolder( "New Folder 2");
objFolder2 = ( new Enumerator( objFolder1 ) ).item(); // an
alternative to Item(0)
// add two different mappings to folder structure
objFolder1.AddFile( strSamplePath + "DB_Altova_SQLXML.mfd");
objMapForce.Documents.OpenDocument(strSamplePath +
"InspectionReport.mfd");
objFolder2.AddActiveFile();
// override code generation settings for this folder
objFolder2.CodeGenSettings_UseDefault = false;
objFolder2.CodeGenSettings_OutputFolder = strSamplePath +
"SampleOutput"
//C++
objFolder2.CodeGenSettings_Language = 1;
// insert Web service project based on a wsdl file from the
installed examples
objProject.InsertWebService( strSamplePath +
"TimeService/TimeService.wsdl",
"{http://www.Nanonull.com/TimeService/}TimeService",
"TimeServiceSoap"
,
true );
objProject.Save();
if ( ! objProject.Saved )
WScript.Echo("problem occurred when saving project");
// dump project tree
strGlobalText = '';
PrintProjectTree( new Enumerator (objProject), ' ' )
WScript.Echo( strGlobalText );
}
catch (err)
{ ERROR("while creating new project", err ); }
}
© 2008 Altova GmbH
Altova MapForce 2008
202
The MapForce API
Overview
// ---------------------------------------------------------// Generate code for a project's sub-tree. Mix default code
// generation parameters and overloaded parameters.
// ---------------------------------------------------------function GenerateCodeForNewProject()
{
// since the Web service project contains only initial mappings,
// we generate code only for our custom folder.
// code generation parameters from project are used for Folder1,
// whereas Folder2 provides overwritten values.
objFolder = objProject.Item(0);
objFolder1.GenerateCode();
}
// /////////////////////// MAIN //////////////////////////////
CreateGlobalObjects();
objMapForce.Visible = true;
LoadSampleProject();
CreateNewProject();
GenerateCodeForNewProject();
// uncomment to shut down application when script ends
// objMapForce.Visible = false;
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
Overview
203
11.1.4 Error handling
The MapForce API returns errors in two different ways. Every API method returns an HRESULT.
This return value informs the caller about any malfunctions during the execution of the method.
If the call was successful, the return value is equal to S_OK. C/C++ programmers generally use
HRESULT to detect errors.
VisualBasic, scripting languages, and other high-level development environments do not give
the programmer access to the returning HRESULT of a COM call. They use the second
error-raising mechanism supported by the MapForce API, the IErrorInfo interface. If an
error occurs, the API creates a new object that implements the IErrorInfo interface. The
development environment takes this interface and fills its own error-handling mechanism with
the provided information.
The following text describes how to deal with errors raised from the MapForce API in different
development environments.
VisualBasic
A common way to handle errors in VisualBasic is to define an error handler. This error handler
can be set with the On Error statement. Usually the handler displays an error message and
does some cleanup to avoid spare references and any kind of resource leaks. VisualBasic fills
its own Err object with the information from the IErrorInfo interface.
Example:
Sub Validate()
'place variable declarations here
'set error handler
On Error GoTo ErrorHandler
'if generation fails, program execution continues at ErrorHandler:
objMapForce.ActiveDocument.GenerateXSLT()
'additional code comes here
'exit
Exit Sub
ErrorHandler:
MsgBox("Error: " & (Err.Number - vbObjectError) & Chr(13) &
"Description: " & Err.Description)
End Sub
JavaScript
The Microsoft implementation of JavaScript (JScript) provides a try-catch mechanism to deal
with errors raised from COM calls. It is very similar to the VisualBasic approach, in that you also
declare an error object containing the necessary information.
Example:
Function Generate()
{
// please insert variable declarations here
try
{
objMapForce.ActiveDocument.GenerateXSLT();
}
catch(Error)
{
© 2008 Altova GmbH
Altova MapForce 2008
204
The MapForce API
Overview
sError = Error.description;
nErrorCode = Error.number & 0xffff;
return false;
}
return true;
}
C/C++
C/C++ gives you easy access to the HRESULT of the COM call and to the IErrorInterface.
H R E S U LThr;
// Call GenerateXSLT() from the MapForce API
If(FAILED(hr = ipDocument->GenerateXSLT()))
{
IErrorInfo *ipErrorInfo = Null;
If(SUCCEEDED(::GetErrorInfo(0, &ipErrorInfo)))
{
BSTRbstrDescr;
ipErrorInfo->GetDescription(&bstrDescr);
// handle Error information
wprintf(L"Error message:\t%s\n",bstrDescr);
::SysFreeString(bstrDescr);
// release Error info
ipErrorInfo->Release();
}
}
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
11.2
Object Reference
205
Object Reference
Object Hierarchy
Application
Options
Project
ProjectItem
Documents
Document
MapForceView
Enumerations
Description
This section contains the reference of the MapForce API 1.0 Type Library.
© 2008 Altova GmbH
Altova MapForce 2008
206
The MapForce API
Object Reference
11.2.1 Application
Properties and Methods
Properties to navigate the object model:
Application
Parent
Options
Project
Documents
Application status:
Visible
Name
Quit
WindowHandle
MapForce designs:
NewDocument
OpenDocument
OpenURL
ActiveDocument
MapForce projects:
NewProject (Enterprise or Professional edition is required)
OpenProject (Enterprise or Professional edition is required)
ActiveProject (Enterprise or Professional edition is required)
MapForce code generation:
HighlightSerializedMarker
Examples
The following examples show how the automation interface of MapForce can be accessed from
different programming environments in different languages.
' ------------------- begin VBA example --------------------' create a new instance of <SPY-MAP>.
Dim objMapForce As Application
Set objMapForce = CreateObject("MapForce.Application")
' -------------------- end example --------------------' ------------------- begin VBScript example --------------------' access a running, or create a new instance of MapForce.
' works with scripts running in the Windows scripting host.
Set objMapForce = GetObject("MapForce.Application");
' -------------------- end example --------------------// ------------------- begin JScript example --------------------// Access a running, or create a new instance of <MapForce
// works with scripts executed in the Windows scripting host
try
{
objMapForce = WScript.GetObject ("", "MapForce.Application");
// unhide application if it is a new instance
objMapForce.Visible = true;
}
catch(err) { WScript.Echo ("Can't access or create MapForce.Application"); }
// -------------------- end example ---------------------
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
Object Reference
207
Events
This object supports the following events:
OnDocumentOpened
OnProjectOpened
OnDocumentOpened
Event: OnDocumentOpened (i_objDocument as Document)
Description
This event is triggered when an existing or new document is opened. The corresponding close
event is Document.OnDocumentClosed.
OnProjectOpened
Event: OnProjectOpened (i_objProject as Project)
Description
This event is triggered when an existing or new project is loaded into the application. The
corresponding close event is Project.OnProjectClosed.
ActiveDocument
Property: ActiveDocument as Document (read-only)
Description
Returns the automation object of the currently active document. This property returns the same
as Documents.ActiveDocument.
Errors
1000
1001
The application object is no longer valid.
Invalid address for the return parameter was specified.
ActiveProject
Property: ActiveProject as Project (read-only)
Description
Returns the automation object of the currently active project.
Errors
1000
1001
The application object is no longer valid.
Invalid address for the return parameter was specified.
Application
Property: Application as Application (read-only)
Description
Retrieves the application's top-level object.
Errors
1000
© 2008 Altova GmbH
The application object is no longer valid.
Altova MapForce 2008
208
The MapForce API
1001
Object Reference
Invalid address for the return parameter was specified.
Documents
Property: Documents as Documents (read-only)
Description
Returns a collection of all currently open documents.
Errors
1000
1001
The application object is no longer valid.
Invalid address for the return parameter was specified.
HighlightSerializedMarker
Method: HighlightSerializedMarker (i_strSerializedMarker as String)
Description
Use this method to highlight a location in a mapping file that has been previously serialized. If
the corresponding document is not already loaded, it will be loaded first. See
Document.GenerateCodeEx for a method to retrieve a serialized marker.
Errors
1000
1001
1007
1008
The application object is no longer valid.
Invalid address for the return parameter was specified.
The string passed in i_strSerializedMarker is not recognized a serialized
MapForce marker.
The marker points to a location that is no longer valid.
Name
Property: Name as String (read-only)
Description
The name of the application.
Errors
1000
1001
The application object is no longer valid.
Invalid address for the return parameter was specified.
NewDocument
Method: NewDocument () as Document
Description
Creates a new empty document. The newly opened document becomes the ActiveDocument
. This method is a shortened form of Documents.NewDocument.
Errors
1000
1001
The application object is no longer valid.
Invalid address for the return parameter was specified.
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
Object Reference
209
NewProject
Method: NewProject () as Project
Description
Creates a new empty project. The current project is closed. The new project is accessible
under Project.
Errors
1000
1001
The application object is no longer valid.
Invalid address for the return parameter was specified.
OpenDocument
Method: OpenDocument (i_strFileName as String) as Document
Description
Loads a previously saved document file and continues working on it. The newly opened
document becomes the ActiveDocument. This method is a shorter form of
Documents.OpenDocument.
Errors
1000
1001
The application object is no longer valid.
Invalid address for the return parameter was specified.
OpenProject
Method: NewProject () as Project
Description
Opens an existing Mapforce project (*.mfp). The current project is closed. The newly opened
project is accessible under Project.
Errors
1000
1001
The application object is no longer valid.
Invalid address for the return parameter was specified.
OpenURL
Method: OpenURL (i_strURL as String, i_strUser as String, i_strPassword as
String)
Description
Loads a previously saved document file from an URL location. Allows user name and password
to be supplied.
Errors
1000
1001
The application object is no longer valid.
Invalid address for the return parameter was specified.
Options
Property: Options as Options (read-only)
Description
© 2008 Altova GmbH
Altova MapForce 2008
210
The MapForce API
Object Reference
This property gives access to options that configure the generation of code.
Errors
1000
1001
The application object is no longer valid.
Invalid address for the return parameter was specified.
Parent
Property: Parent as Application (read-only)
Description
The parent object according to the object model.
Errors
1000
1001
The application object is no longer valid.
Invalid address for the return parameter was specified.
Project
Property: Project as Project (read-only)
Description
Returns the MapForce project currently open. If no project is open, retuns null.
Errors
1000
1001
The application object is no longer valid.
Invalid address for the return parameter was specified.
Quit
Method: Quit ()
Description
Disconnects from MapForce to allow the application to shutdown. Calling this method is optional
since MapForce keeps track of all external COM connections and automatically recognizes a
disconnection. For more information on automatic shutdown see the Visible property.
Errors
1000
1001
The application object is no longer valid.
Invalid address for the return parameter was specified.
Visible
Property: Visible as Boolean
Description
True if MapForce is displayed on the screen (though it might be covered by other applications
s e if MapForce is hidden. The default value for MapForce when
or be iconized). Fal
automatically started due to a request from the automation server MapForce.Application
is false. In all other cases, the property is initialized to true.
An application instance that is visible is said to be controlled by the user (and possibly by clients
connected via the automation interface). It will only shut down due to an explicit user request.
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
Object Reference
211
To shut down an application instance, set its visibility to false and clear all references to this
instance within your program. The application instance will shut down automatically when no
further COM clients are holding references to it.
Errors
1000
1001
The application object is no longer valid.
Invalid address for the return parameter was specified.
WindowHandle
Property: WindowHandle () as long (read-only)
Description
Retrieve the application's Window Handle.
Errors
1000
1001
© 2008 Altova GmbH
The application object is no longer valid.
Invalid address for the return parameter was specified.
Altova MapForce 2008
212
The MapForce API
Object Reference
11.2.2 MapForceView
Properties and Methods
Properties to navigate the object model:
Application
Parent
View activation and view properties:
Active
ShowItemTypes
ShowLibraryInFunctionHeader
HighlightMyConnections
HighlightMyConnectionsRecursivly
Adding items:
InsertXMLFile
InsertXMLSchema
InsertXMLSchemaWithSample
Active
Property: Active as Boolean
Description
Use this property to query if the mapping view is the active view, or set this view to be the active
one.
Errors
1300
1301
The application object is no longer valid.
Invalid address for the return parameter was specified.
Application
Property: Application as Application (read-only)
Description
Retrieves the application's top-level object.
Errors
1300
1301
The application object is no longer valid.
Invalid address for the return parameter was specified.
HighlightMyConnections
Property: HighlightMyConnections as Boolean
Description
This property defines whether connections from the selected item only should be highlighed.
Errors
1300
1301
The application object is no longer valid.
Invalid address for the return parameter was specified.
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
Object Reference
213
HighlightMyConnectionsRecursivey
Property: HighlightMyConnectionsRecursively as Boolean
Description
This property defines if only the connections coming directly or indirectly from the selected item
should be highlighed.
Errors
1300
1301
The application object is no longer valid.
Invalid address for the return parameter was specified.
InsertXMLFile
Method: InsertXMLFile (i_strXMLFileName as String, i_strRootElement as
String)
Description
Adds a new item to the mapping. The item's internal structure is determined by the schema
defined in the specified XML file. The second parameter defines the root element of this
schema, if there is more than one candidate. The specified XML file is used as the input sample
to evaluate the mapping.
Errors
1300
1301
The application object is no longer valid.
Invalid address for the return parameter was specified.
InsertXMLSchema
Method: InsertXMLSchema (i_strSchemaFileName as String, i_strRootElement
as String)
Description
Adds a new item to the mapping. The item's internal structure is determined by the specified
schema file. The second parameter defines the root element of this schema if there is more
then one candidate. No XML input sample is assigned to this item.
Errors
1300
1301
The application object is no longer valid.
Invalid address for the return parameter was specified.
InsertXMLSchemaWithSample
Method: InsertXMLSchemaWithSample (i_strSchemaFileName as String,
i_strXMLSampleName as String, i_strRootElement as String)
Description
Adds a new item to the mapping. The item's internal structure is determined by the specified
schema file. The second parameter is stored as the XML input sample for mapping
evaluation.The third parameter defines the root element of this schema if there is more then
one candidate.
Errors
1300
1301
© 2008 Altova GmbH
The application object is no longer valid.
Invalid address for the return parameter was specified.
Altova MapForce 2008
214
The MapForce API
Object Reference
Parent
Property: Parent as Document (read-only)
Description
The parent object according to the object model.
Errors
1300
1301
The application object is no longer valid.
Invalid address for the return parameter was specified.
ShowItemTypes
Property: ShowItemTypes as Boolean
Description
This property defines if types of items should be shown in the mapping diagram.
Errors
1300
1301
The application object is no longer valid.
Invalid address for the return parameter was specified.
ShowLibraryInFunctionHeader
Property: ShowLibraryInFunctionHeader as Boolean
Description
This property defines whether the name of the function library should be part of function names.
Errors
1300
1301
The application object is no longer valid.
Invalid address for the return parameter was specified.
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
Object Reference
215
11.2.3 Document
Properties and Methods
Properties to navigate the object model:
Application
Parent
File handling:
FullName
Name
Path
Saved
Save
SaveAs
Close
Code generation:
OutputSettings_ApplicationName
OutputSettings_Encoding
JavaSettings_BasePackageName
GenerateXSLT
GenerateCppCode
GenerateJavaCode
GenerateCHashCode
GenerateCodeEx
HighlightSerializedMarker
View access:
MapForceView
Events
This object supports the following events:
OnDocumentClosed
OnModifiedFlagChanged
OnDocumentClosed
Event: OnDocumentClosed (i_objDocument as Document)
Description
This event is triggered when a document is closed. The document object passed into the event
handler should not be accessed. The corresponding open event is
Application.OnDocumentOpened.
OnModifiedFlagChanged
Event: OnModifiedFlagChanged (i_bIsModified as Boolean)
Description
This event is triggered when a document's modification status changes.
© 2008 Altova GmbH
Altova MapForce 2008
216
The MapForce API
Object Reference
Activate
Method: Activate ()
Description
Makes this document the active document.
Errors
1200
The application object is no longer valid.
Application
Property: Application as Application (read-only)
Description
Retrieves the application's top-level object.
Errors
1200
1201
The application object is no longer valid.
Invalid address for the return parameter was specified.
Close
Method: Close ()
Description
Closes the document without saving.
Errors
1200
1201
The application object is no longer valid.
Invalid address for the return parameter was specified.
FullName
ri
ng
Property: FullName as St
Description
Path and name of the document file.
Errors
1200
1201
The application object is no longer valid.
Invalid address for the return parameter was specified.
GenerateCHashCode
Method: GenerateCHashCode ()
Description
Generate C# code that will perform the mapping. Uses the properties defined in
Application.Options to configure code generation.
Errors
1200
The application object is no longer valid.
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
1201
1205
Object Reference
217
Invalid address for the return parameter was specified.
Error during code generation.
See also
Code Generation
GenerateCppCode
Method: GenerateCppCode ()
Description
Generates C++ code that will perform the mapping. Uses the properties defined in
Application.Options to configure code generation.
Errors
1200
1201
1205
The application object is no longer valid.
Invalid address for the return parameter was specified.
Error during code generation.
See also
Code Generation
GenerateCodeEx
Method: GenerateCodeEx (i_nLanguage as ENUMProgrammingLanguage) as
ErrorMarkers
Description
Generates C++ code that will perform the mapping. The parameter i_nLanguage specifies the
target language. The method returns an object that can be used to enumerate all messages
created the code generator. These are the same messages that get displayed in the Messages
window of MapForce.
Errors
1200
1201
1205
The application object is no longer valid.
Invalid address for the return parameter was specified.
Error during code generation.
See also
Code Generation
GenerateJavaCode
Method: GenerateJavaCode ()
Description
Generates Java code that will perform the mapping. Uses the properties defined in
Application.Options to configure code generation.
Errors
1200
1201
1205
The application object is no longer valid.
Invalid address for the return parameter was specified.
Error during code generation.
See also
© 2008 Altova GmbH
Altova MapForce 2008
218
The MapForce API
Object Reference
Code Generation
GenerateOutput
Method: GenerateOutput ()
Description
Generates all output files defined in the mapping using a MapForce internal mapping language.
The names of the output files are defined as properties of the output items in the mapping.
Errors
1200
1201
1206
The application object is no longer valid.
Invalid address for the return parameter was specified.
Error during execution of mapping algorithm.
See also
Code Generation
GenerateXQuery
Method: GenerateXQuery ()
Description
Generates mapping code as XQuery. Uses the properties defined in Application.Options to
configure code generation.
Errors
1200
1201
1204
The application object is no longer valid.
Invalid address for the return parameter was specified.
Error during XSLT/XSLT2/XQuery code generation.
See also
Code Generation
GenerateXSLT
Method: GenerateXSLT ()
Description
Generates mapping code as XSLT. Uses the properties defined in Application.Options to
configure code generation.
Errors
1200
1201
1204
The application object is no longer valid.
Invalid address for the return parameter was specified.
Error during XSLT/XSLT2/XQuery code generation.
See also
Code Generation
GenerateXSLT2
Method: GenerateXSLT2 ()
Description
Generates mapping code as XSLT2. Uses the properties defined in Application.Options to
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
Object Reference
219
configure code generation.
Errors
1200
1201
1204
The application object is no longer valid.
Invalid address for the return parameter was specified.
Error during XSLT/XSLT2/XQuery code generation.
See also
Code Generation
HighlightSerializedMarker
Method: HighlightSerializedMarker (i_strSerializedMarker as String)
Description
Use this method to highlight a location in a mapping file that has been previously serialized. If
the corresponding document is not already loaded, it will be loaded first. See GenerateCodeEx
for a method to retrieve a serialized marker.
Errors
1000
1001
1007
1008
The application object is no longer valid.
Invalid address for the return parameter was specified.
The string passed in i_strSerializedMarker is not recognized a serialized
MapForce marker.
The marker points to a location that is no longer valid.
JavaSettings_BasePackageName
Property: JavaSettings_BasePackageName as String
Description
Sets or retrieves the base package name used when generating Java code. This property is
available in UI-dialog for the Document Settings.
Errors
1200
1201
The application object is no longer valid.
Invalid address for the return parameter was specified.
See also
Code Generation
MapForceView
Property: MapForceView as Document (read-only)
Description
This property gives access to functionality specific to the MapForce view.
Errors
1200
1201
© 2008 Altova GmbH
The application object is no longer valid.
Invalid address for the return parameter was specified.
Altova MapForce 2008
220
The MapForce API
Object Reference
Name
ri
ng
Property: Name as St
Description
Name of the document file without file path.
Errors
1200
1201
The application object is no longer valid.
Invalid address for the return parameter was specified.
OutputSettings_ApplicationName
Property: OutpuSettings_ApplicationName as String
Description
Sets or retrieves the application name available in the Document Settings dialog.
Errors
1200
1201
The application object is no longer valid.
Invalid address for the return parameter was specified.
See also
Code Generation
OutputSettings_Encoding
Property: OutputSettings_Encoding as String
Description
Sets or retrieves the output encoding available in the Document Settings dialog.
Errors
1200
1201
The application object is no longer valid.
Invalid address for the return parameter was specified.
See also
Code Generation
Parent
i
cati
on
Property: Parent as Appl
(read-only)
Description
The parent object according to the object model.
Errors
1200
1201
The application object is no longer valid.
Invalid address for the return parameter was specified.
Path
ri
ng
Property: Path as St
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
Object Reference
221
Description
Path of the document file without name.
Errors
1200
1201
The application object is no longer valid.
Invalid address for the return parameter was specified.
Save
Method: Save ()
Description
Save the document to the file defined by Document.FullName.
Errors
1200
1201
The application object is no longer valid.
Invalid address for the return parameter was specified.
SaveAs
ri
ng )
Method: SaveAs (i_strFileName as St
Description
Save document to specified file name, and set Document.FullName to this value if save
operation was successful.
Errors
1200
1201
The application object is no longer valid.
Invalid address for the return parameter was specified.
Saved
Property: Saved as Boolean (read-only)
Description
True if the document was not modified since the last save operation, f
al
se
Errors
1200
1201
© 2008 Altova GmbH
otherwise.
The application object is no longer valid.
Invalid address for the return parameter was specified.
Altova MapForce 2008
222
The MapForce API
Object Reference
11.2.4 Documents
Properties and Methods
Properties to navigate the object model:
Application
Parent
Open and create mappings:
OpenDocument
NewDocument
Iterating through the collection:
Count
Item
ActiveDocument
Application
Property: Application as Application (read-only)
Description
Retrieves the application's top-level object.
Errors
1600
1601
The object is no longer valid.
Invalid address for the return parameter was specified.
Parent
Property: Parent as Application (read-only)
Description
Retrieves the application's top-level object.
Errors
1600
1601
The object is no longer valid.
Invalid address for the return parameter was specified.
Count
Property: Count as Integer (read-only)
Description
Retrieves the number of documents in the collection.
Errors
1600
1601
The object is no longer valid.
Invalid address for the return parameter was specified.
Item
Property: Item (nIndex as Integer) as Document (read-only)
Description
Retrieves the document at nIndex from the collection. Indices start with 1.
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
Errors
1600
1601
Object Reference
223
The object is no longer valid.
Invalid address for the return parameter was specified.
NewDocument
Method: NewDocument () as Document
Description
Creates a new document, adds it to the end of the collection, and makes it the active document.
Errors
1600
1601
The object is no longer valid.
Invalid address for the return parameter was specified.
OpenDocument
Method: OpenDocument (strFilePath as String) as Document
Description
Opens an existing mapping document (*.mfd). Adds the newly opened document to the end of
the collection and makes it the active document.
Errors
1600
1601
The object is no longer valid.
Invalid address for the return parameter was specified.
ActiveDocument
Property: ActiveDocument as Document (read-only)
Description
Retrieves the active document. If no document is open, null is returned.
Errors
1600
1601
© 2008 Altova GmbH
The object is no longer valid.
Invalid address for the return parameter was specified.
Altova MapForce 2008
224
The MapForce API
Object Reference
11.2.5 ErrorMarkers
Properties and Methods
Properties to navigate the object model:
Application
Parent
Iterating through the collection:
Count
Item
Application
Property: Application as Application (read-only)
Description
Retrieves the application's top-level object.
Errors
1800
1801
The object is no longer valid.
Invalid address for the return parameter was specified.
Count
Property: Count as Integer (read-only)
Description
Retrieves the number of error markers in the collection.
Errors
1800
1801
The object is no longer valid.
Invalid address for the return parameter was specified.
Item
Property: Item (nIndex as Integer) as ErrorMarker (read-only)
Description
Retrieves the error marker at nIndex from the collection. Indices start with 1.
Errors
1800
1801
The object is no longer valid.
Invalid address for the return parameter was specified.
Parent
Property: Parent as Application (read-only)
Description
Retrieves the application's top-level object.
Errors
1800
1801
The object is no longer valid.
Invalid address for the return parameter was specified.
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
© 2008 Altova GmbH
Object Reference
225
Altova MapForce 2008
226
The MapForce API
Object Reference
11.2.6 ErrorMarker
Properties and Methods
Properties to navigate the object model:
Application
Parent
Access to message information:
Application
Property: Application as Application (read-only)
Description
Retrieves the application's top-level object.
Errors
1900
1901
The object is no longer valid.
Invalid address for the return parameter was specified.
DocumentFileName
Property: DocumentFileName as String (read-only)
Description
Retrieves the name of the mapping file that the error marker is associated with.
Errors
1900
1901
The object is no longer valid.
Invalid address for the return parameter was specified.
ErrorLevel
Property: ErrorLevel as ENUMCodeGenErrorLevel (read-only)
Description
Retrieves the severity of the error.
Errors
1900
1901
The object is no longer valid.
Invalid address for the return parameter was specified.
Highlight
Method: Highlight()
Description
Highlights the item that the error marker is associated with. If the corresponding document is
not open, it will be opened.
Errors
1900
1901
1008
The object is no longer valid.
Invalid address for the return parameter was specified.
The marker points to a location that is no longer valid.
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
Object Reference
227
Serialization
Property: Serialization as String (read-only)
Description
Serialize error marker into a string. Use this string in calls to
Application.HighlightSerializedMarker or Document.HighlightSerializedMarker to highlight the
marked item in the mapping. The string can be persisted and used in other instantiations of
MapForce or its Control.
Errors
1900
1901
The object is no longer valid.
Invalid address for the return parameter was specified.
Text
Property: Text as String (read-only)
Description
Retrieves the message text.
Errors
1900
1901
The object is no longer valid.
Invalid address for the return parameter was specified.
Parent
Property: Parent as Application (read-only)
Description
Retrieves the application's top-level object.
Errors
1900
1901
© 2008 Altova GmbH
The object is no longer valid.
Invalid address for the return parameter was specified.
Altova MapForce 2008
228
The MapForce API
Object Reference
11.2.7 Options
This object gives access to all MapForce options available in the Tools | Options dialog.
Properties and Methods
Properties to navigate the object model:
Application
Parent
General options:
ShowLogoOnPrint
ShowLogoOnStartup
UseGradientBackground
Options for code generation:
CompatibilityMode
DefaultOutputEncoding
XSLTDefaultOutputDirectory
CodeDefaultOutputDirectory
CppSettings_DOMType
CppSettings_LibraryType
CppSettings_UseMFC
CppSettings_GenerateVC6ProjectFile
CppSettings_GenerateVSProjectFile
CSharpSettings_ProjectType
Application
Property: Application as Application (read-only)
Description
Retrieves the application's top-level object.
Errors
1400
1401
The application object is no longer valid.
Invalid address for the return parameter was specified.
CodeDefaultOutputDirectory
Property: CodeDefaultOutputDirectory as String
Description
Specifies the target directory where files generated by Document.GenerateCppCode,
Document.GenerateJavaCode and Document.GenerateCHashCode, are placed.
Errors
1400
1401
The application object is no longer valid.
Invalid address for the return parameter was specified.
See also
Code Generation
CompatibilityMode
Property: CompatibilityMode as Boolean
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
Object Reference
229
Description
Set to true to generate code compatible with Version 2005R3. Set to false to use newly added
code generation features in Document.GenerateCppCode,
Document.GenerateCHashCode, Document.GenerateJavaCode and
Document.GenerateXSLT
Errors
1400
1401
The application object is no longer valid.
Invalid address for the return parameter was specified.
See also
Code Generation
CppSettings_DOMType
Property: CppSettings_DOMType as ENUMDOMType
Description
Specifies the DOM type used by Document.GenerateCppCode.
Errors
1400
1401
The application object is no longer valid.
Invalid address for the return parameter was specified.
See also
Code Generation
CppSettings_GenerateVC6ProjectFile
Property: CppSettings_GenerateVC6ProjectFile as Boolean
Description
Specifies if VisualC++ 6.0 project files should be generated by Document.GenerateCppCode.
Errors
1400
1401
The application object is no longer valid.
Invalid address for the return parameter was specified.
See also
Code Generation
CppSettings_GenerateVSProjectFile
Property: CSharpSettings_GenerateVSProjectFile as ENUMProjectType
Description
Specifies which version of VisualStudio project files should be generated by
Document.GenerateCppCode.
Only eVisualStudio2003Project and eVisualStudio2005Project are valid
selections.
Errors
1400
1401
© 2008 Altova GmbH
The application object is no longer valid.
Invalid address for the return parameter was specified.
Altova MapForce 2008
230
The MapForce API
Object Reference
See also
Code Generation
CppSettings_LibraryType
Property: CppSettings_LibraryType as ENUMLibType
Description
Specifies the library type used by Document.GenerateCppCode.
Errors
1400
1401
The application object is no longer valid.
Invalid address for the return parameter was specified.
See also
Code Generation
CppSettings_UseMFC
Property: CppSettings_UseMFC as Boolean
Description
Specifies if MFC support should be used by C++ code generated by
Document.GenerateCppCode.
Errors
1400
1401
The application object is no longer valid.
Invalid address for the return parameter was specified.
See also
Code Generation
CSharpSettings_ProjectType
Property: CSharpSettings_ProjectType as ENUMProjectType
Description
Specifies the type of C# project used by Document.GenerateCHashCode.
Errors
1400
1401
The application object is no longer valid.
Invalid address for the return parameter was specified.
See also
Code Generation
DefaultOutputEncoding
Property: DefaultOutputEncoding as Boolean
Description
File encoding used for output files.
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
Errors
1400
1401
Object Reference
231
The application object is no longer valid.
Invalid address for the return parameter was specified.
See also
Code Generation
Parent
i
cati
on
Property: Parent as Appl
(read-only)
Description
The parent object according to the object model.
Errors
1400
1401
The application object is no longer valid.
Invalid address for the return parameter was specified.
ShowLogoOnPrint
Property: ShowLogoOnPrint as Boolean
Description
Show or hide the MapForce logo on printed outputs.
Errors
1400
1401
The application object is no longer valid.
Invalid address for the return parameter was specified.
ShowLogoOnStartup
Property: ShowLogoOnStartup as Boolean
Description
Show or hide the MapForce logo on application startup.
Errors
1400
1401
The application object is no longer valid.
Invalid address for the return parameter was specified.
UseGradientBackground
Property: UseGradientBackground as Boolean
Description
Set or retrieve the background color mode for a mapping window.
Errors
1400
1401
© 2008 Altova GmbH
The application object is no longer valid.
Invalid address for the return parameter was specified.
Altova MapForce 2008
232
The MapForce API
Object Reference
XSLTDefaultOutputDirectory
Property: XSLTDefaultOutputDirectory as String
Description
Specifies the target directory where files generated by Document.GenerateXSLT are placed.
Errors
1400
1401
The application object is no longer valid.
Invalid address for the return parameter was specified.
See also
Code Generation
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
Object Reference
233
11.2.8 Project (Enterprise or Professional Edition)
Properties and Methods
Properties to navigate the object model:
Application
Parent
File handling:
FullName
Name
Path
Saved
Save
Close
Project tree navigation:
Count
Item
_NewEnum
Project tree manipulation:
AddActiveFile
AddFile
InsertWebService (Enterprise edition only)
CreateFolder
Code-generation:
Output_Folder
Output_Language
Output_TextEncoding
Java_BasePackageName
GenerateCode
GenerateCodeEx
GenerateCodeIn
GenerateCodeInEx
For examples of how to use the properties and methods listed above, see Example: Project
Support. Note that, in order to use these properties and methods, you will need to have the
Enterprise or Professional edition of MapForce installed on your computer. For operations with
Web services, the Enterprise edition is required.
_NewEnum
Property: _NewEnum () as IUnknown (read-only)
Description
This property supports language-specific standard enumeration.
Errors
1500
The object is no longer valid.
Examples
// -----------------------------------------------------------// JScript sample - enumeration of a project's project items.
function AllChildrenOfProjectRoot()
{
objProject = objMapForce.ActiveProject;
© 2008 Altova GmbH
Altova MapForce 2008
234
The MapForce API
Object Reference
if ( objProject != null )
{
for ( objProjectIter = new Enumerator(objProject); !
objProjectIter.atEnd(); objProjectIter.moveNext() )
{
objProjectItem = objProjectIter.item();
// do something with project item here
}
}
}
// -----------------------------------------------------------// JScript sample - iterate all project items, depth first.
function IterateProjectItemsRec(objProjectItemIter)
{
while ( ! objProjectItemIter.atEnd() )
{
objProjectItem = objProjectItemIter.item();
// do something with project item here
IterateProjectItemsRec( new Enumerator(objProjectItem) );
objProjectItemIter.moveNext();
}
}
function IterateAllProjectItems()
{
objProject = objMapForce.ActiveProject;
if ( objProject != null )
{
IterateProjectItemsRec( new Enumerator(objProject) );
}
}
Events
This object supports the following events:
OnProjectClosed
OnProjectClosed
Event: OnProjectClosed (i_objProject as Project)
Description
This event is triggered when the project is closed. The project object passed into the event
handler should not be accessed. The corresponding open event is
Application.OnProjectOpened.
AddActiveFile
Method: AddActiveFile () as ProjectItem
Description
Adds the currently open document to the mapping folder of the project's root.
Errors
1500
1501
The object is no longer valid.
Invalid address for the return parameter was specified.
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
1503
1504
1705
Object Reference
235
No active document is available.
Active documents needs to be given a path name before it can be added
to the project.
Mapping could not be assigned to project. Maybe it is already contained
in the target folder.
AddFile
Method: AddFile (i_strFileName as String) as ProjectItem
Description
Adds the specified document to the mapping folder of the project's root.
Errors
1500
1501
1705
The object is no longer valid.
The file name is empty.
Invalid address for the return parameter was specified.
Mapping could not be assigned to project.
The file does not exist or is not a MapForce mapping.
Maybe the file is already assigned to the target folder.
Application
Property: Application as Application (read-only)
Description
Retrieves the top-level application object.
Errors
1500
1501
The object is no longer valid.
Invalid address for the return parameter was specified.
Close
Method: Close ()
Description
Closes the project without saving.
Errors
1500
The object is no longer valid.
Count
Property: Count as Integer (read-only)
Description
Retrieves number of children of the project's root item.
Errors
1500
The object is no longer valid.
Examples
See Item or _NewEnum.
© 2008 Altova GmbH
Altova MapForce 2008
236
The MapForce API
Object Reference
CreateFolder
Method: CreateFolder (i_strFolderName as String) as ProjectItem
Description
Creates a new folder as a child of the project's root item.
Errors
1500
1501
The object is no longer valid.
Invalid folder name or invalid address for the return parameter was specified.
FullName
ri
ng
Property: FullName as St
(read-only)
Description
Path and name of the project file.
Errors
1500
1501
The object is no longer valid.
Invalid address for the return parameter was specified.
GenerateCode
Method: GenerateCode ()
Description
Generates code for all project items of the project. The code language and output location is
determined by properties of the project and project items.
Errors
1500
1706
The object is no longer valid.
Error during code generation
GenerateCodeEx
Method: GenerateCode () as ErrorMarkers
Description
Generates code for all project items of the project. The code language and output location are
determined by properties of the project and project items. An object that can be used to iterate
through all messages issued by the code generation process is returned. These messages are
the same as those shown in the Messages window of MapForce.
Errors
1500
1501
1706
The object is no longer valid.
Invalid address for the return parameter was specified.
Error during code generation
GenerateCodeIn
Method: GenerateCodeIn (i_nLanguage as ENUMProgrammingLanguage)
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
Object Reference
237
Description
Generates code for all project items of the project in the specified language. The output location
is determined by properties of the project and project items.
Errors
1500
1706
The object is no longer valid.
Error during code generation
GenerateCodeInEx
Method: GenerateCodeIn (i_nLanguage as ENUMProgrammingLanguage) as
ErrorMarkers
Description
Generates code for all project items of the project in the specified language. The output location
is determined by properties of the project and project items. An object that can be used to
iterate through all messages issued by the code generation process is returned. These
messages are the same as those shown in the Messages window of MapForce.
Errors
1500
1501
1706
The object is no longer valid.
Invalid address for the return parameter was specified.
Error during code generation
InsertWebService
Method: InsertWebService (i_strWSDLFile as String, i_strService as String,
i_strPort as String, i_bGenerateMappings as Boolean) as ProjectItem
Description
Inserts a new Web service project into the project's Web service folder. If
i_bGenerateMappings is true, initial mapping documents for all ports get generated
automatically.
Errors
1500
1501
1503
The object is no longer valid.
WSDL file can not be found or is invalid.
Service or port names are invalid.
Invalid address for the return parameter was specified.
Operation not supported by current edition.
Item
Property: Item(i_nItemIndex as Integer) as ProjectItem (read-only)
Description
Returns the child at i_nItemIndex position of the project's root. The index is zero-based. The
largest valid index is Count-1. For an alternative to visit all children see _NewEnum.
Errors
1500
The object is no longer valid.
Examples
// -----------------------------------------------------------
© 2008 Altova GmbH
Altova MapForce 2008
238
The MapForce API
Object Reference
// JScript code snippet - enumerate children using Count and Item.
for( nItemIndex = 0; nItemIndex < objProject.Count; nItemIndex++ )
{
objProjectItem = objProject.Item(nItemIndex);
// do something with project item here
}
Java_BasePackageName
Property: Java_BasePackageName as String
Description
Sets or gets the base package name of the Java packages that will be generated. This property
is used only when generating Java code.
Errors
1500
1501
The object is no longer valid.
Invalid package name specified.
Invalid address for the return parameter was specified.
Name
ri
ng
Property: Name as St
(read-only)
Description
Name of the project file without file path.
Errors
1500
1501
The object is no longer valid.
Invalid address for the return parameter was specified.
Output_Folder
Property: Output_Folder as String
Description
Sets or gets the default output folder used with GenerateCode and GenerateCodeIn. Project
items can overwrite this value in their CodeGenSettings_OutputFolder property, when
CodeGenSettings_UseDefault is set to false.
Errors
1500
1501
The object is no longer valid.
Invalid folder name specified.
Invalid address for the return parameter was specified.
Output_Language
Property: OutputLanguage as ENUMProgrammingLanguage
Description
Sets or gets the default language for code generation when using GenerateCode. Project
items can overwrite this value in their CodeGenSettings_OutputLanguage property, when
CodeGenSettings_UseDefault is set to false.
Errors
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
1500
1501
Object Reference
239
The object is no longer valid.
Invalid language specified.
Invalid address for the return parameter was specified.
Output_TextEncoding
Property: Output_TextEncoding as String
Description
Sets or gets the text encoding used when generating XML-based code.
Errors
1500
1501
The object is no longer valid.
Invalid text encoding specified.
Invalid address for the return parameter was specified.
Parent
Property: Parent as Application (read-only)
Description
Retrieves the top-level application object.
Errors
1500
1501
The is no longer valid.
Invalid address for the return parameter was specified.
Path
ri
ng
Property: Path as St
(read-only)
Description
Path of the project file without name.
Errors
1500
1501
The object is no longer valid.
Invalid address for the return parameter was specified.
Save
Method: Save ()
Description
Saves the project to the file defined by FullName.
Errors
1500
1502
The object is no longer valid.
Can't save to file.
Saved
Property: Saved as Boolean (read-only)
Description
© 2008 Altova GmbH
Altova MapForce 2008
240
The MapForce API
True if the project was not modified since the last Save operation, f
al
se
Errors
1500
1501
Object Reference
otherwise.
The object is no longer valid.
Invalid address for the return parameter was specified.
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
Object Reference
241
11.2.9 ProjectItem (Enterprise or Professional Edition)
Properties and Methods
Properties to navigate the object model:
Application
Parent
Project tree navigation:
Count
Item
_NewEnum
Project item properties:
Kind
Name
WSDLFile (only available to Web service project items)
QualifiedName (only available to Web service project items)
Project tree manipulation:
AddActiveFile (only available to folder items)
AddFile (only available to folder items)
CreateFolder (only available to folder items)
CreateMappingForProject (only available to Web service operations)
Remove
Document access:
Open (only available to mapping items and Web service operations)
Code-generation:
CodeGenSettings_UseDefault
CodeGenSettings_OutputFolder
CodeGenSettings_Language
GenerateCode
GenerateCodeEx
GenerateCodeIn
GenerateCodeInEx
For examples of how to use the properties and methods listed above, see Example: Project
Support. Note that, in order to use these properties and methods, you will need to have the
Enterprise or Professional edition of MapForce installed on your computer. For operations with
Web services, the Enterprise edition is required.
_NewEnum
Property: _NewEnum () as IUnknown (read-only)
Description
This property supports language specific standard enumeration.
Errors
1700
The object is no longer valid.
Examples
See Project.Item or Project._NewEnum.
© 2008 Altova GmbH
Altova MapForce 2008
242
The MapForce API
Object Reference
AddActiveFile
Method: AddActiveFile () as ProjectItem
Description
Adds the currently active document to this project item if it is a valid child. Otherwise, the
document is added to the Mapping Folder of the project's root.
Errors
1700
1701
1703
1704
1705
The object is no longer valid.
The file name is empty.
Invalid address for the return parameter was specified.
No active document is available.
Active documents needs to be given a path name before it can be added
to the project.
Mapping could not be assigned to project.
The file does not exist or is not a MapForce mapping.
Maybe the file is already assigned to the target folder.
AddFile
Method: AddFile (i_strFileName as String) as ProjectItem
Description
Adds the specified document to this project item if it is a valid child. Otherwise, the document is
added to the Mapping Folder of the project's root.
Errors
1700
1701
1705
The object is no longer valid.
The file name is empty.
Invalid address for the return parameter was specified.
Mapping could not be assigned to project.
The file does not exist or is not a MapForce mapping.
Maybe the file is already assigned to the target folder.
Application
Property: Application as Application (read-only)
Description
Retrieves the top-level application object.
Errors
1700
1701
The object is no longer valid.
Invalid address for the return parameter was specified.
CodeGenSettings_Language
Property: CodeGenSettings_Language as ENUMProgrammingLanguage
Description
Gets or sets the language to be used with GenerateCode or Project.GenerateCode. This
property is consulted only if CodeGenSettings_UseDefault is set to false.
Errors
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
1700
1701
Object Reference
243
The object is no longer valid.
Invalid language or invalid address for the return parameter was
specified.
CodeGenSettings_OutputFolder
Property: CodeGenSettings_OutputFolder as String
Description
Gets or sets the output directory to be used with GenerateCode, GenerateCodeIn,
Project.GenerateCode or Project.GenerateCodeIn. This property is consulted only if
CodeGenSettings_UseDefault is set to false.
Errors
1700
1701
The object is no longer valid.
An invalid output folder or an invalid address for the return parameter was
specified.
CodeGenSettings_UseDefault
Property: CodeGenSettings_UseDefault as Boolean
Description
Gets or sets whether output directory and code language are used as defined by either (a) the
parent folders, or (b) the project root. This property is used with calls to GenerateCode,
GenerateCodeIn, Project.GenerateCode and Project.GenerateCodeIn. If this property is
set to false, the values of CodeGenSettings_OutputFolder and
CodeGenSettings_Language are used to generate code for this project item..
Errors
1700
1701
The object is no longer valid.
Invalid address for the return parameter was specified.
Count
Property: Count as Integer (read-only)
Description
Retrieves number of children of this project item. Also see Item.
Errors
1700
The object is no longer valid.
Examples
See Project.Item or Project._NewEnum.
CreateFolder
Method: CreateFolder (i_strFolderName as String) as ProjectItem
Description
Creates a new folder as a child of this project item.
Errors
© 2008 Altova GmbH
Altova MapForce 2008
244
The MapForce API
1700
1701
1702
Object Reference
The object is no longer valid.
Invalid folder name or invalid address for the return parameter was specified.
The project item does not support children.
CreateMappingForProject
Method: CreateMappingForProject (i_strFileName as String) as ProjectItem
Description
Creates an initial mapping document for a Web service operation and saves it to
i_strFileName. When using Project.InsertWebService you can use the
i_bGenerateMappings flag to let MapForce automatically generate initial mappings for all
ports.
Errors
1700
1701
1707
1708
The object is no longer valid.
Invalid address for the return parameter was specified.
Cannot create new mapping.
The project item does not support auto-creation of initial mappings or a
mapping already exists.
Operation not supported in current edition.
GenerateCode
Method: GenerateCode ()
Description
Generates code for this project item and its children. The code language and output location is
determined by CodeGenSettings_UseDefault, CodeGenSettings_Language and
CodeGenSettings_OutputFolder. Children of this project item can have their own property
settings related to code-generation.
Errors
1700
1706
The object is no longer valid.
Error during code generation.
GenerateCodeEx
Method: GenerateCode () as ErrorMarkers
Description
Generates code for this project item and its children. The code language and output location are
determined by CodeGenSettings_UseDefault, CodeGenSettings_Language and
CodeGenSettings_OutputFolder. Children of this project item can have their own property
settings related to code-generation.
An object that can be used to iterate through all messages issued by the code generation
process is returned. These messages are the same as those shown in the Messages window of
MapForce.
Errors
1700
1701
1706
The object is no longer valid.
Invalid address for the return parameter was specified.
Error during code generation.
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
Object Reference
245
GenerateCodeIn
Method: GenerateCodeIn (i_nLanguage as ENUMProgrammingLanguage)
Description
Generates code for the project item and its children in the specified language. The output
location is determined by CodeGenSettings_UseDefault and
CodeGenSettings_OutputFolder. Children of this project item can have their own property
settings related to code-generation.
Errors
1700
1701
1706
The object is no longer valid.
Invalid language specified.
Error during code generation.
GenerateCodeInEx
Method: GenerateCodeIn (i_nLanguage as ENUMProgrammingLanguage) as
ErrorMarkers
Description
Generates code for the project item and its children in the specified language. The output
location is determined by CodeGenSettings_UseDefault and
CodeGenSettings_OutputFolder. Children of this project item can have their own property
settings related to code-generation.
An object that can be used to iterate through all messages issued by the code generation
process is returned. These messages are the same as those shown in the Messages window
of MapForce.
Errors
1700
1701
1706
The object is no longer valid.
Invalid language specified or invalid address for the return parameter
was specified.
Error during code generation.
Item
Property: Item(i_nItemIndex as Integer) as ProjectItem (read-only)
Description
Returns the child at i_nItemIndex position of this project item. The index is zero-based. The
largest valid index is Count - 1.
For an alternative to visit all children see _NewEnum.
Errors
1700
The object is no longer valid.
Examples
See Project.Item or Project._NewEnum.
Kind
Property: Kind as ENUMProjectItemType (read-only)
Description
© 2008 Altova GmbH
Altova MapForce 2008
246
The MapForce API
Object Reference
Retrieves the kind of the project item. Availability of some properties and the applicability of
certain methods is restricted to specific kinds of project items. The description of all methods
and properties contains information about these restrictions.
Errors
1700
1701
The object is no longer valid.
Invalid address for the return parameter was specified.
Name
Property: Name as String
Description
Retrieves or sets the name of a project item. The name of most items is read-only. Exceptions
are user-created folders, the names of which can be altered after creation.
Errors
1700
1701
1702
The object is no longer valid.
Invalid address for the return parameter was specified.
Project item does not allow to alter its name.
Open
Method: Open () as Document
Description
Opens the project item as a document or makes the corresponding document the active one, if
it is already open. The project item must be a MapForce mapping or, for Enterprise edition only,
Web service operation.
Errors
1700
1701
1702
1708
The object is no longer valid.
Invalid address for the return parameter was specified.
The project item does not refer to a MapForce mapping file.
Operation not supported in current edition.
Parent
Property: Parent as Project (read-only)
Description
Retrieves the project that this item is a child of. Has the same effect as
Application.ActiveProject.
Errors
1700
1701
The object is no longer valid.
Invalid address for the return parameter was specified.
QualifiedName
Property: QualifiedName as String (read-only)
Description
Retrieves the qualified name of a Web service item.
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
Errors
1700
1701
1702
Object Reference
247
The object is no longer valid.
Invalid address for the return parameter was specified.
The project item is not a part of a Web service.
Remove
Method: Remove ()
Description
Remove this project item and all its children from the project tree.
Errors
1700
The object is no longer valid.
WSDLFile
Property: WSDLFile as String (read-only)
Description
Retrieves the file name of the WSDL file defining the Web service that hosts the current project
item.
Errors
1700
1701
1702
© 2008 Altova GmbH
The object is no longer valid.
Invalid address for the return parameter was specified.
The project item is not a part of a Web service.
Altova MapForce 2008
248
The MapForce API
11.3
Enumerations
Enumerations
This is a list of all enumerations used by the MapForce API. If your scripting environment does
not support enumerations, use the number-values instead.
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
Enumerations
249
11.3.1 ENUMCodeGenErrorLevel
Description
Enumeration values to identify severity of code generation messages.
Possible values:
eCodeGenErrorLevel_Information
eCodeGenErrorLevel_Warning
eCodeGenErrorLevel_Error
eCodeGenErrorLevel_Undefined
© 2008 Altova GmbH
=0
=1
=2
=3
Altova MapForce 2008
250
The MapForce API
Enumerations
11.3.2 ENUMDOMType
Description
Enumeration values to specify the DOM type used by generated C++ mapping code.
Possible values:
eDOMType_msxml4
eDOMType_xerces
=0
=1
See also
Code Generation
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
Enumerations
251
11.3.3 ENUMLibType
Description
Enumeration values to specify the library type used by the generated C++ mapping code.
Possible values:
eLibType_static
eLibType_dll
=0
=1
See also
Code Generation
© 2008 Altova GmbH
Altova MapForce 2008
252
The MapForce API
Enumerations
11.3.4 ENUMProgrammingLanguage
Description
Enumeration values to select a programming language.
Possible values:
eUndefinedLanguage
eJava
eCpp
eCSharp
eXSLT
eXSLT2
eXQuery
Altova MapForce 2008
= -1
=0
=1
=2
=3
=4
=5
© 2008 Altova GmbH
The MapForce API
Enumerations
253
11.3.5 ENUMProjectItemType
WDescription
Enumeration the different kinds of project items that can be children of Project or folder-like
ProjectItems.
Possible values:
eProjectItemType_Invalid
= -1
eProjectItemType_MappingFolder
=0
eProjectItemType_Mapping
=1
eProjectItemType_WebServiceFolder = 2
eProjectItemType_WebServiceRoot
=3
eProjectItemType_WebServiceService = 4
eProjectItemType_WebServicePort
=5
eProjectItemType_WebServiceOperatio = 6
n
eProjectItemType_ExternalFolder
=7
eProjectItemType_LibrarzFolder
=8
eProjectItemType_ResourceFolder
=9
eProjectItemType_VirtualFolder
= 10
See also
ProjectItem.Kind
© 2008 Altova GmbH
Altova MapForce 2008
254
The MapForce API
Enumerations
11.3.6 ENUMProjectType
Description
Enumeration values to select a project type for generated C# mapping code.
Possible values:
eVisualStudioProject
eVisualStudio2003Project
eBorlandProject
eMonoMakefile
eVisualStudio2005Project
=0
=1
=2
=3
=4
See also
Code Generation
Altova MapForce 2008
© 2008 Altova GmbH
The MapForce API
Enumerations
255
11.3.7 ENUMViewMode
Description
Enumeration values to select a MapForce view.
Possible values:
eMapForceView
eXSLView
eOutputView
© 2008 Altova GmbH
=0
=1
=2
Altova MapForce 2008
Chapter 12
MapForceControl
258
MapForceControl
12
MapForceControl
MapForceControl is a control that provides a means of integration of the MapForce user
interface and the functionality described in this section into most kinds of applications. ActiveX
technology was chosen so as to allow integration using any of a wide variety of languages; this
enables C++, C#, VisualBasic, or HTML to be used for integration. All components are full OLE
Controls, which makes integration as simple as possible. Two different levels of integration are
provided, thus enabling the integration to be adapted to a wide range of needs.
For a successful integration you have to consider the following main design factors:



What technology or programming language can the hosting application use to integrate
the MapForceControl?
Should the integrated UI look exactly like MapForce with all its menus, toolbars, and
windows, or will a subset of these elements—like allowing only one document and a
restricted set of commands—be more effective?
How deep will the integration be? Should the MapForce user interface be used as is?
Are user interface extensions and/or restrictions required? Can some frequently used
tasks be automated?
The sections, Integration at the Application Level and Integration at Document Level, both of
which have examples in various programming languages, will help you to make the right
decisions quickly. The section, Object Reference, describes all COM objects that can be used
for integration, together with their properties and methods.
For automation tasks, the MapForce Automation Interface is accessible from the
MapForceControl as well.
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
12.1
Integration at the Application Level
259
Integration at the Application Level
Integration at application level is simple and straightforward. It allows you to embed the
complete interface of MapForce into a window of your application. Since you get the whole user
interface of MapForce, you get all menus, toolbars, the status bar, document windows, and
helper windows. Customization of the application's user interface is restricted to what MapForce
provides. This includes rearrangement and resizing of helper windows and customization of
menus and toolbars.
The only ActiveX control you need to integrate is MapForceControl. Its property
IntegrationLevel defaults to application-level. You may use Appearance and
BorderStyle to configure the appearance of the control's wrapper window. Do not instantiate
or access MapForceControlDocument or MapForceControlPlaceHolder ActiveX
controls when integrating at application-level.
If you have any initialization to do or if you want to automate some behaviour of MapForce, use
the properties, methods, and events described for MapForceControl. Consider using
MapForceControl.Application for more complex access to MapForce functionality.
In this section is an example (Example: HTML) showing how the MapForce application can be
embedded in an HTML page. For usage with other programming languages, or more
sophisticated access, see the Examples of integration at document-level.
© 2008 Altova GmbH
Altova MapForce 2008
260
MapForceControl
Integration at the Application Level
12.1.1 Example: HTML
This example shows a simple integration of the MapForce control at application-level into a
HTML page. The integration is described in the following sections:



Instantiate a MapForceControl in HTML code.
Implement buttons to load documents and automate code-generation tasks.
Define actions for some application events.
The code for this example is available at the following location in your MapForce installation:
MapForceExamples\ActiveX\HTML\MapForceActiveX_ApplicationLevel.htm.
Instantiate the Control
The HTML Object tag is used to create an instance of the MapForceControl. The Classid is
that of MapForceControl. Width and height specify the window size. No additional parameters
are necessary, since application-level is the default.
<OBJECT id="objMapForceControl"
Classid="clsid:A38637E9-5759-4456-A167-F01160CC22C1"
width="800"
height="500"
VIEWASTEXT>
</OBJECT>
Add Button to Open Default Document
As a simple example of how to automate some tasks, we add a button to the page:
<input type="button" value="Open Marketing Expenses"
onclick="BtnOpenMEFile()">
When clicked, a predefined document will be opened in the MapForceControl. We use a
method to locate the file relative to the MapForceControl so the example can run on different
installations.
<SCRIPT ID=Javahandlers LANGUAGE=javascript>
// --------------------------------// open a pre-defined document
function BtnOpenMEFile()
{
objMapForceControl.Open("C:\Documents and Settings\username\My
Documents\Altova\XMLSpy2008\Examples/MarketingExpenses.mfd");
}
</SCRIPT>
Add Buttons for Code Generation
Although code-generation for the active document is available via menus, we want to have
buttons that will generate code without asking the user for the location of the output. The
method is similar to that used in the previous section.
First come the buttons:
<input
<input
<input
<input
type="button"
type="button"
type="button"
type="button"
Altova MapForce 2008
value="Generate
value="Generate
value="Generate
value="Generate
XSLT" onclick="BtnGenerate( 0 )">
Java" onclick="BtnGenerate( 1 )">
C++" onclick="BtnGenerate( 2 )">
C#" onclick="BtnGenerate( 3 )">
© 2008 Altova GmbH
MapForceControl
Integration at the Application Level
261
Then we provide the script that will generate the code into sub-folders of the currently defined
default output folders.
<SCRIPT ID=Javahandlers LANGUAGE=javascript>
// ---------------------------------------------------------------------// generate code for active document into language-specific sub folders of
// the current default output directory. No user interaction necessary.
function BtnGenerate(languageID)
{
// get top-level object of automation interface
var objApp = objMapForceControl.Application;
// get the active document
var objDocument = objApp.ActiveDocument;
// retrieve object to set the generation output path
var objOptions = objApp.Options;
if ( objDocument == null )
alert( "no active document found" );
else
{
if (languageID == 0)
{
objOptions.XSLTDefaultOutputDirectory
objOptions.XSLTDefaultOutputDirectory + "\\XSLTGen";
objDocument .GenerateXSLT();
}
else if (languageID == 1)
{
objOptions.CodeDefaultOutputDirectory
objOptions.CodeDefaultOutputDirectory + "/JavaCode";
objDocument .GenerateJavaCode();
}
else if (languageID == 2)
{
objOptions.CodeDefaultOutputDirectory
objOptions.CodeDefaultOutputDirectory + "/CPPCode";
objDocument .GenerateCppCode();
}
else if (languageID == 3)
{
objOptions.CodeDefaultOutputDirectory
objOptions.CodeDefaultOutputDirectory + "/CSharpCode";
objDocument .GenerateCHashCode();
}
}
}
</SCRIPT>
=
=
=
=
Connect to Custom Events
The example implements two event callbacks for MapForceControl custom events to show the
principle:
<!-- ----------------------------------------------------------- -->
<!-- custom event 'OnDocumentOpened" of MapForceControl object -->
<SCRIPT FOR="objMapForceControl" event="OnDocumentOpened( objDocument )"
LANGUAGE="javascript">
// alert("Document '" + objDocument.Name + "' opened!");
</SCRIPT>
<!-- ----------------------------------------------------------- -->
© 2008 Altova GmbH
Altova MapForce 2008
262
MapForceControl
Integration at the Application Level
<!-- custom event 'OnDocumentClosed" of MapForceControl object -->
<SCRIPT FOR="objMapForceControl" event="OnDocumentClosed( objDocument )"
LANGUAGE="javascript">
// alert("Document '" + objDocument.Name + "' closed!");
</SCRIPT>
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
12.2
Integration at Document Level
263
Integration at Document Level
Integration at document level gives you freedom over instantiation and placement of the
following parts of the MapForce user interface:





Editing windows for MapForce mappings
MapForce overview window
MapForce library window
MapForce validation window
MapForce project window
If necessary, a replacement for the menus and toolbars of MapForce must be provided by your
application.
You will need to instantiate and access multiple ActiveX controls, depending on which user
interface parts you want to re-use. All these controls are contained in the MapForceControl
OCX.




Use MapForceControl to set the integration level and access application wide
functionality.
Use MapForceControlDocument to create any number of editor windows. It may be
sufficient to create only one window and re-use it for different mapping files, depending
on your needs.
Optionally Use MapForceControlPlaceholder to embed MapForce overview, library,
validation and project windows.
Access run-time information about commands, menus, and toolbars available in
MapForceControl to seamlessly integrate these commands into your application's
menus and toolbars. See Use MapForceCommands for more information.
If you want to automate some behaviour of MapForce use the properties, methods, and events
described for the MapForceControl, MapForceControlDocument and
MapForceControlPlaceHolder. Consider using MapForceControl.Application,
MapForceControlDocument.Document and MapForceControlPlaceHolder.Project for more
complex access to MapForce functionality. However, to open a document always use
MapForceControlDocument.OpenDocument or MapForceControlDocument.NewDocument on
the appropriate document control. To open a project always use
MapForceControlPlaceHolder.OpenProject on a placeholder control embedding a MapForce
project window.
See Examples on how to instantiate and access the necessary controls in different
programming environments.
© 2008 Altova GmbH
Altova MapForce 2008
264
MapForceControl
Integration at Document Level
12.2.1 Use MapForceControl
To integrate at document level, instantiate a MapForceControl first. Set the property
. Set the window size of the
IntegrationLevel to ICActiveXIntegrationOnDocum entLevel(= 1)
embedding window to 0x0 to hide any user interface behind the control. You may use
Appearance and BorderStyle to configure the appearance of the control's wrapper window.
Avoid using the method Open since this might lead to unexpected results. Use the
corresponding open methods of MapForceControlDocument and
MapForceControlPlaceHolder, instead.
See Query MapForce Commands for a description of how to integrate MapForce commands
into your application. Send commands to MapForce via the method Exec. Query if a command
is currently enabled or disabled using the method QueryStatus.
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
Integration at Document Level
265
12.2.2 Use MapForceControlDocument
An instance of the MapForceControlDocument ActiveX control allows you to embed one
MapForce mapping editing window into your application. You can use any number of instances
you need. Each instance will have one mapping loaded. New instances contain a new mapping
at creation. Use the method OpenDocument to load any other existing mapping file.
The control supports a read-only mode via the property ReadOnly.
Use Path and SaveDocument or methods and properties accessible via the property
Document to access document functionality.
© 2008 Altova GmbH
Altova MapForce 2008
266
MapForceControl
Integration at Document Level
12.2.3 Use MapForceControlPlaceHolder
Instances of MapForceControlPlaceHolder ActiveX controls allow you to selectively embed the
additional helper windows of MapForce into your application. The property
PlaceholderWindowID selects the MapForce helper window to be embedded. Use only one
MapForceControlPlaceHolder for each window identifier. See
Enumerations.MapForceControlPlaceholderWindow for valid window identifiers.
For placeholder controls that select the MapForce project window, additional methods are
available. Use OpenProject to load a MapForce project. Use the property Project and the
methods and properties from the MapForce automation interface to perform any other project
related operations.
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
Integration at Document Level
267
12.2.4 Query MapForce Commands
When integrating at document-level, no menu or toolbar from MapForce is available to your
application. Instead, you can query all the commands and the structure of the application menu
at runtime. Use the property MapForceControl.CommandsStructure to access this
information. Professional applications will need to integrate this menu in a sophisticated manner
into their own menu structure. Your installation of MapForce even provides you with command
label images used within MapForce. See the folder MapForceExamples\ActiveX\Images
of your MapForce installation for icons in GIF format. The file names correspond to the labels
of commands.
See the C# Example for details of how to use the command structure information to create a
menu at runtime.
© 2008 Altova GmbH
Altova MapForce 2008
268
MapForceControl
Integration at Document Level
12.2.5 Examples
This section contains examples of MapForce document-level integration using different
container environments and programming languages. Source code for all examples is available
in the folder MapForceExamples\ActiveX of your MapForce installation.
C#
The C# example shows how to integrate the MapForceControl in a common desktop application
created with C# using Visual Studio .NET 2003. The following topics are covered:




Building a dynamic menu bar based on information the MapForceControl API provides.
Usage of MapForce Placeholder controls in a standard frame window.
Usage of a MapForce Placeholder control in a sizeable Tool Window.
How to handle an event raised by the MapForceControl API.
Please note that the example application is already complete. There is no need to change
anything if you want to run and see it working. The following steps describe what general
actions and considerations must be taken in order to create a project such as this.
Introduction
Adding the MapForce components to the Toolbox
Before you take a look at the sample project please add the assemblies to the .NET IDE
Toolbox. The MapForce Installer will have already installed the assemblies in the .NET Global
Assembly Cache (GAC). If you open the Toolbox dialog under Tools | Add/Remove Toolbox
Items the controls will appear as AxMapForceControl, AxMapForceControlDocument
and AxMapForceControlPlaceholder on the .NET Framework Components tab. Check all
to make them available to the IDE.
Now you can open the MapForceApplication.sln file in the
ActiveX\C#\MapForceApplication folder to load the project.
Placing the MapForceControl
It is necessary to have one MapForceControl instance to set the integration level and to
manage the Document and Placeholder controls of the MapForce library. The control is
accessible via the General section of the Toolbox helper window in the IDE. To add it you need
to select the component in the Toolbox window and drag a rectangle wherever you want to have
it in the destination window. If you have an application which does not open a window on startup
you can use a simple invisible Form with the control on it which is created manually in the code.
The example project adds this instance to the main MdiContainer MDIMain. If you open
MDIMain in the Design View from the Solution Explorer you will see a light blue rectangle at the
top-left side in the client area of the Frame window. Selecting this rectangle will show you the
properties of the MapForceControl. It is important to set the IntegrationLevel property to
ICActiveXIntegrationOnDocumentLevel in order to turn on the Document and
Placeholder support of the MapForce library. Properties of the MapForceControl component
placed in the MDIFrame Window of the example application are shown below:
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
Integration at Document Level
269
Set the Visible flag to False to avoid any confusion about the control for the user.
Adding the Placeholder Controls
Placeholders on the MDI Frame
The example project has to place Placeholder controls on the main MDI Frame. They are also
added via the Toolbox window by dragging a rectangle on the destination Form. To set the type
of the Placeholder which should be displayed one has to set the PlaceholderWindowID
property. This property can also be changed during runtime in the code of the application. The
Placeholder control would change its content immediately.
Properties of the Library window on the left side of the MDIMain Frame window are shown
below:
© 2008 Altova GmbH
Altova MapForce 2008
270
MapForceControl
Integration at Document Level
Properties of the Output window at the bottom:
The Placeholders also have the Anchor and Dock properties set in order to react on resizing of
the Frame window.
Placeholder on a separate Toolwindow
It is also possible to place a Placeholder control on a separate floating Toolwindow. To do this,
create a new Form as a Toolwindow and add the control as shown above. The
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
Integration at Document Level
271
MapForceOverviewWnd in the sample project contains the Overview window of MapForce.
Properties of the Overview Toolwindow:
However, all Placeholder controls need a connection to the main MapForceControl. Normally
this connection can be established automatically and there is nothing more to do. The two
placeholders on the MDI Frame work like this. In the case of the Placeholder control in the
Toolwindow, we need to add some code to the public MDIMain() method in MDIMain.cs:
m_MapForceOverview = new MapForceOverviewWnd();
MapForceControlLib.MapForceControlPlaceHolderClass type =
(MapForceControlLib.MapForceControlPlaceHolderClass)m_MapForceOverview.axM
apForceControlOverview.GetOcx();
type.AssignMultiDocCtrl((MapForceControlLib.MapForceControlClass)axMapForc
eControl.GetOcx());
m_MapForceOverview.Show();
The MapForceOverviewWnd is created and shown here. In addition, a special method of the
Placeholder control is called in order to connect the MapForcecontrol to it.
AssignMultiDocCtrl() takes the MapForceControl as parameter and registers a reference
to it in the Placeholder control.
Retrieving Command Information
The MapForceControl gives access to all commands of MapForce through its
Com m andsStructure property. The example project uses the MapForceCommands and
MapForceCommand interfaces to dynamically build a menu in the MDI Frame window which
contains most of the MapForce commands.
The code to add the commands is placed in the MDIMain method of the
MapForceApplication class in the file MDIMain.cs:
public MDIMain()
© 2008 Altova GmbH
Altova MapForce 2008
272
MapForceControl
Integration at Document Level
{
.
.
.
MFLib.MapForceCommands objCommands;
objCommands = axMapForceControl.CommandsStructure;
long nCount = objCommands.Count;
for(long idx = 0;idx < nCount;idx++)
{
MFLib.MapForceCommandobjCommand;
objCommand = objCommands[(int)idx];
// We are looking for the Menu with the name IDR_MAPFORCE. This menu
contains
// the complete main menu of MapForce.
if(objCommand.Label == "IDR_MAPFORCE")
{
InsertMenuStructure(mainMenu.MenuItems, 1, objCommand, 0, 0,
false);
}
}
.
.
.
}
mainMenu is the name of the menu object of the MDI Frame window created in the Visual
Studio IDE. InsertMenuStructure takes the MapForce menu from the IDR_MAPFORCE
command object and adds the MapForce menu structure to the already existing menu of the
sample project. No commands from the File, Project, or Window menu are added.
The new commands are instances of the class CustomMenuItem, which is defined in
CustomMenuItem.cs. This class has an additional member to save the MapForce command
ID, which is taken to execute the command using Exec on selecting the menu item. This code
from InsertMenuStructure creates the new command:
CustomMenuItem
newMenuItem = new CustomMenuItem();
if(objCommand.IsSeparator)
newMenuItem.Text = "-";
else
{
newMenuItem.Text = strLabel;
newMenuItem.m_MapForceCmdID = (int)objCommand.ID;
newMenuItem.Click += new EventHandler(AltovaMenuItem_Click);
}
You can see that all commands get the same event handler
AltovaMenuItem_Click which does the processing of the command:
private void AltovaMenuItem_Click(object sender, EventArgs e)
{
if(sender.GetType() ==
System.Type.GetType("MapForceApplication.CustomMenuItem"))
{
CustomMenuItem customItem = (CustomMenuItem)sender;
ProcessCommand(customItem.m_MapForceCmdID);
}
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
Integration at Document Level
273
}
private void ProcessCommand(int nID)
{
MapForceDoc docMapForce = GetCurrentMapForceDoc();
if(docMapForce != null)
docMapForce.axMapForceControlDoc.Exec(nID);
else
axMapForceControl.Exec(nID);
}
ProcessCommand delegates the execution either to the MapForceControl itself or to any active
MapForce document loaded in a MapForceControlDocument control. This is necessary
because the MapForceControl has no way to know which document is currently active in the
hosting application.
Handling Events
Because all events in the MapForce library are based on connection points, you can use the C#
delegate mechanism to provide the custom event handlers. You will always find a complete list
of events on the property page of each control of the MapForce library. The picture below
shows the events of the main MapForceControl:
As you can see, the example project only overrides the OnFileExternalChange event. The
creation of the C# delegate is done for you by the C# Framework. All you need to do is to fill the
empty event handler. The handler implementation turns off any file reloading and displays a
message box to inform the user that a file loaded by the MapForceControl has been changed
from outside:
private void axMapForceControl_OnFileExternalChange(object sender,
© 2008 Altova GmbH
Altova MapForce 2008
274
MapForceControl
Integration at Document Level
AxMapForceControlLib._DMapForceControlEvents_OnFileExternalChangeEvent e)
{
MessageBox.Show("Attention: The file " + e.strPath + " has been changed
from outside\nbut reloading is turned off in the sample application!");
// This turns off any file reloading:
e.varRet = false;
}
Testing the Example
After adding the assemblies to the Toolbox (see Introduction), you can run the sample project
with F5 without the need to change anything in the code. The main MDI Frame window is
created together with a floating Toolwindow containing the Overview window of MapForce. The
application looks something like the screenshot below:
The floating Overview Toolwindow is also created:
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
Integration at Document Level
275
Use File | Open to open the file MarketingExpenses.mfd, which is in the MapForce
examples folder. The file is loaded and displayed in an own document child window:
After you load the document, you can try using menu commands. Note that context menus are
also available. If you like, you can also load additional documents. Save any modifications using
the File | Save command.
© 2008 Altova GmbH
Altova MapForce 2008
276
MapForceControl
Integration at Document Level
HTML
This example shows an integration of the MapForce control at document-level into a HTML
page. The following topics are covered:







Instantiate a MapForceControl ActiveX control object in HTML code
Instantiate a MapForceControlDocument ActiveX control to allow editing a MapForce
mapping
Instantiate one MapForceControlPlaceHolder for a MapForce project window
Instantiate one MapForceControlPlaceHolder ActiveX control to alternatively host one of
the MapForce helper windows
Create a customer toolbar for some heavy-used MapForce commands
Add some more buttons and sample automation code
Use event handlers to update command buttons
This example is available in its entirety in the file
MapForceActiveX_ApplicationLevel.htm within the
MapForceExamples\ActiveX\HTML\ folder of your MapForce installation.
Instantiate the MapForceControl
The HTML OBJECT tag is used to create an instance of the MapForceControl. The Classid is
that of MapForceControl. Width and height are set to 0 since we use this control as manager
control without use for its user interface. The integration level is specified as a parameter within
the OBJECT tag.
<OBJECT id="objMapForceX"
Classid="clsid:A38637E9-5759-4456-A167-F01160CC22C1"
width="0"
height="0"
VIEWASTEXT>
<PARAM NAME="IntegrationLevel" VALUE="1">
</OBJECT>
Create Editor window
The HTML OBJECT tag is used to embed a document editing window. The additional custom
parameter specifies that the control is to be initialized with a new empty mapping.
<OBJECT id="objDoc1"
Classid="clsid:DFBB0871-DAFE-4502-BB66-08CEB7DF5255"
width="600"
height="500"
VIEWASTEXT>
<PARAM NAME="NewDocument">
</OBJECT>
Create Project Window
The HTML OBJECT tag is used to create a MapForceControlPlaceHolder window. The first
additional custom parameter defines the placeholder to show the MapForce project window.
The second parameter loads one of the example projects delivered coming with your MapForce
installation.
<OBJECT id="objProjectWindow"
Classid="clsid:FDEC3B04-05F2-427d-988C-F03A85DE53C2"
width="200"
height="200"
VIEWASTEXT>
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
Integration at Document Level
277
<PARAM name="PlaceholderWindowID" value="3">
<PARAM name="FileName" value="MapForceExamples/MapForceExamples.mfp">
</OBJECT>
Create Placeholder for MapForce Helper Windows
The HTML OBJECT tag is used to instantiate a MapForceControlPlaceHolder ActiveX control
that can host the different MapForce helper window. Initially, no helper window is shown.
<OBJECT id="objPlaceholderWindow"
Classid="clsid:FDEC3B04-05F2-427d-988C-F03A85DE53C2"
width="200"
height="200"
VIEWASTEXT>
<PARAM name="PlaceholderWindowID" value="0">
</OBJECT>
Three buttons allow us to switch the actual window that will be shown. The JavaScript execute
on-button-click sets the property PlaceHolderWindowID to the corresponding value defined in
MapForceControlPlaceholderWindow.
<input type="button" value="Library Window" onclick="BtnHelperWindow(0)">
<input type="button" value="Overview Window" onclick="BtnHelperWindow(1)">
<input type="button" value="Validation Window" onclick="BtnHelperWindow(2)">
<SCRIPT ID="Javahandlers" LANGUAGE="javascript">
//
-----------------------------------------------------------------------------// specify which of the helper windows shall be shown in the placeholder
control.
function BtnHelperWindow(i_ePlaceholderWindowID)
{
objPlaceholderWindow.PlaceholderWindowID = i_ePlaceholderWindowID;
}
</SCRIPT>
Create a Custom Toolbar
The custom toolbar consists of buttons with images of MapForce commands.
<button id="btnInsertXML" title="Insert XML Schema/File"
onclick="BtnDoCommand(13635)">
<img src="..\Images\ID_INSERT_XSD.gif" width="16" height="16" />
</button>
<button id="btnInsertDB" title="Insert Database"
onclick="BtnDoCommand(13590)">
<img src="..\Images\ID_INSERT_DATABASE.gif" width="16" height="16" />
</button>
<button id="btnInsertEDI" title="Insert EDI" onclick="BtnDoCommand(13591)">
<img src="..\Images\ID_INSERT_EDI.gif" width="16" height="16" />
</button>
...
...
On clicking one of these buttons the corresponding command Id is sent to the manager control.
<SCRIPT ID="Javahandlers" LANGUAGE="javascript">
// --------------------------------------------------------------// perform any command specified by cmdID.
// command routing includes application, active document and view.
function BtnDoCommand(cmdID)
{
© 2008 Altova GmbH
Altova MapForce 2008
278
MapForceControl
Integration at Document Level
objMapForceX.Exec( cmdID );
msgtext.innerText = "Command " + cmdID + " performed.";
}
</SCRIPT>
Create More Buttons
In the example, we add some more buttons to show some automation code.
<p>
<input type="button" value="New File" onclick="BtnNewFile(objDoc1)">
<input type="button" value="Save File" onclick="BtnSaveFile(objDoc1)">
<input type="text" title="Path" id="strPath" width="150">
<input type="button" value="Open MarketingExpenses"
onclick="BtnOpenMEFile(objDoc1)">
</p>
<p>
<input type="button" id="GenerateXSLT"
value="Generate XSLT"
onclick="BtnGenerate( objDoc1, 0 )">
<input type="button" id="GenerateJava"
value="Generate Java"
onclick="BtnGenerate( objDoc1, 1 )">
<input type="button" id="GenerateCpp"
value="Generate C++"
onclick="BtnGenerate( objDoc1, 2 )">
<input type="button" id="GenerateCSharp" value="Generate C#"
onclick="BtnGenerate( objDoc1, 3 )">
</p>
The corresponding JavaScript looks like this:
<SCRIPT ID="Javahandlers" LANGUAGE="javascript">
// --------------------------------------------------------// open a document in the specified document control window.
function BtnOpenMEFile(objDocCtrl)
{
// do not use MapForceX.Application.OpenDocument(...) to open a
document,
// since then MapForceControl wouldn't know a control window to show
// the document in. Instead:
objDocCtrl.OpenDocument("C:\Documents and Settings\username\My
Documents\
Altova\XMLSpy2008\Examples/MarketingExpenses.mfd");
objDocCtrl.setActive();
}
// ------------------------------------------------------------------// open a new empty document in the specified document control window.
function BtnNewFile(objDocCtrl)
{
objDocCtrl.OpenDocument("");
objDocCtrl.setActive();
}
// ------------------------------------------------------------------// Saves the current file in the specified document control window.
function BtnSaveFile(objDocCtrl)
{
if(objDocCtrl.Path.length > 0)
objDocCtrl.SaveDocument();
else
{
if(strPath.value.length > 0)
{
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
Integration at Document Level
279
objDocCtrl.Path = strPath.value;
objDocCtrl.SaveDocument();
}
else
{
alert("Please set path for the document first!");
strPath.focus();
}
}
objDocCtrl.setActive();
}
</SCRIPT>
Create Event Handler to Update Button Status
Availability of a command may vary with every mouseclick or keystroke. The custom event
OnUpdateCmdUI of MapForceControl gives us an opportunity to update the enabled/disabled
state of buttons associated with MapForce commands. The method
MapForceControl.QueryStatus is used to query whether a command is enabled or not.
<SCRIPT FOR="objMapForceX" event="OnUpdateCmdUI()" LANGUAGE="javascript">
// 'complete'
if ( document.readyState == "complete" )
{
// update status of buttons
GenerateXSLT.disabled = ! (objDoc1.QueryStatus(13617) & 0x02);
// not enabled
GenerateJava.disabled = ! (objDoc1.QueryStatus(13587) & 0x02);
// not enabled
GenerateCpp.disabled =
! (objDoc1.QueryStatus(13589) & 0x02);
// not enabled
GenerateCSharp.disabled = ! (objDoc1.QueryStatus(13588) & 0x02);
// not enabled
btnFuncUserDef.disabled = ! (objDoc1.QueryStatus(13633) & 0x02);
btnFuncUserDefSel.disabled = ! (objDoc1.QueryStatus(13634) &
0x02);
btnFuncSettings.disabled = ! (objDoc1.QueryStatus(13632) & 0x02
);
btnInsertInput.disabled = ! (objDoc1.QueryStatus(13491) & 0x02);
btnGenXSLT.disabled = ! (objDoc1.QueryStatus(13617) & 0x02);
btnGenXSLT2.disabled = ! (objDoc1.QueryStatus(13618) & 0x02);
btnGenXQuery.disabled = ! (objDoc1.QueryStatus(13586) & 0x02);
btnGenCPP.disabled = ! (objDoc1.QueryStatus(13589) & 0x02);
btnGenCSharp.disabled = ! (objDoc1.QueryStatus(13588) & 0x02);
btnGenJava.disabled = ! (objDoc1.QueryStatus(13587) & 0x02);
}
// set activity status of simulated toolbar
</SCRIPT>
Visual Basic
Source code for an integration of MapForceControl into a VisualBasic program can be found in
the folder MapForceExamples\ActiveX\VisualBasic6 relative to your MapForce
installation.
© 2008 Altova GmbH
Altova MapForce 2008
280
MapForceControl
12.3
Command Table
Command Table
Tables in this section list the names and identifiers of all commands that are available within
MapForce. Every sub-section lists the commands from the corresponding top-level menu of
MapForce. The left-most column shows the command's menu text to make it easier for you to
identify the functionality behind the command. The last sub-section is a collection of those
commands that are not accessible via the main menu.
Depending on the edition of MapForce you have installed, some of these commands might not
be supported. See Query MapForce Commands on how to query the current resource
structure and command availability. The same topics shows how to use the same command
icons that are used by MapForce if you are not already integrating on application-level.
Use the command identifiers with MapForceControl.QueryStatus or
MapForceControlDocument.QueryStatus to check the current status of a command. Use
MapForceControl.Exec or MapForceControlDocument.Exec to execute a command.
File Menu
Edit Menu
Insert Menu
Project Menu
Component Menu
Connection Menu
Function Menu
Output Menu
View Menu
Tools Menu
Window Menu
Help Menu
Commands not in Main Menu
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
Command Table
281
12.3.1 File Menu
Commands from the File menu:
Menu Text
Command Name
ID
New...
ID_FILE_NEW
57600
Open...
ID_FILE_OPEN
57601
Save
ID_FILE_SAVE
57603
Save As...
ID_FILE_SAVE_AS
57604
Save All
ID_FILE_SAVEALL
32377
Close
ID_WINDOW_CLOSE
32453
Close All
ID_WINDOW_CLOSEALL
32454
Save Project
ID_FILE_SAVEPROJECT
32378
Close Project
ID_FILE_CLOSEPROJECT
32355
Print...
IDC_FILE_PRINT
57607
Print Preview
IDC_FILE_PRINT_PREVIEW
57609
Print Setup...
ID_FILE_PRINT_SETUP
57606
Generate code in selected language
ID_FILE_GENERATE_SELECTED_CODE
32362
Generate code in/XSLT 1.0
ID_FILE_GENERATEXSLT
32360
Generate code in/XSLT 2.0
ID_FILE_GENERATEXSLT2
32361
Generate code in/XQuery
ID_FILE_GENERATEXQUERY
32359
Generate code in/Java
ID_FILE_GENERATEJAVACODE
32358
Generate code in/C# (Sharp)
ID_FILE_GENERATECSCODE
32357
Generate code in/C++
ID_FILE_GENERATECPPCODE
32356
Mapping Settings...
ID_MAPPING_SETTINGS
32396
Recent Files/Recent File
ID_FILE_MRU_FILE1
57616
Recent Projects/Recent Project
ID_FILE_MRU_PROJECT1
32364
Exit
ID_APP_EXIT
57665
© 2008 Altova GmbH
Altova MapForce 2008
282
MapForceControl
Command Table
12.3.2 Edit Menu
Commands from the Edit menu:
Menu Text
Command Name
ID
Undo
ID_EDIT_UNDO
57643
Redo
ID_EDIT_REDO
57644
Find...
ID_EDIT_FIND
57636
Find next
ID_EDIT_FINDNEXT
32349
Cut
ID_EDIT_CUT
57635
Copy
ID_EDIT_COPY
57634
Paste
ID_EDIT_PASTE
57637
Delete
ID_EDIT_CLEAR
57632
Select All
ID_EDIT_SELECT_ALL
57642
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
Command Table
283
12.3.3 Insert Menu
Commands from the Insert menu:
Menu Text
Command Name
ID
XML Schema/File
ID_INSERT_XSD
32393
Database
ID_INSERT_DATABASE
32389
EDI
ID_INSERT_EDI
32390
Text file
ID_INSERT_TXT
32392
Constant
ID_INSERT_CONSTANT
32388
Filter: Nodes/Rows
ID_INSERT_FILTER
32391
IF-Else Condition
ID_INSRT_CONDITION
32394
Exception
ID_INSERT_EXCEPTION
32311
© 2008 Altova GmbH
Altova MapForce 2008
284
MapForceControl
Command Table
12.3.4 Project Menu
Commands from the Project menu:
Menu Text
Command Name
ID
Add Files to Project...
ID_PROJECT_ADDFILESTOPROJECT
32420
Add Active File to Project...
ID_PROJECT_ADDACTIVEFILETOPROJECT
32419
Create Folder
ID_POPUP_PROJECT_CREATE_FOLDER
32310
Open Mapping for Operation
ID_POPUP_OPENOPERATIONSMAPPING
13692
Create Mapping for Operation...
ID_POPUP_CREATEMAPPINGFOROPERATION
32399
Add Mapping File for Operation...
ID_POPUP_PROJECT_ADD_MAPPING
32309
Remove Item
ID_PROJECT_REMOVE_ITEM
32415
Insert Web Service...
ID_POPUP_PROJECT_INSERT_WEBSERVICE
32306
Open WSDL file In XMLSpy
ID_POPUP_PROJECT_OPENINXMLSPY
32305
Generate Code for Entire Project
ID_POPUP_PROJECT_GENERATE_PROJECT
32304
Generate code in/XSLT 1.0
ID_PROJECT_GENERATEXSLT
32425
Generate code in/XSLT 2.0
ID_PROJECT_GENERATEXSLT2
32426
Generate code in/XQuery
ID_PROJECT_GENERATEXQUERY
32424
Generate code in/Java
ID_PROJECT_GENERATEJAVACODE
32423
Generate code in/C# (Sharp)
ID_PROJECT_GENERATECSCODE
32422
Generate code in/C++
ID_PROJECT_GENERATECPPCODE
32421
Project Settings...
ID_PROJECT_PROPERTIES
32404
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
Command Table
285
12.3.5 Component Menu
Commands from the Component menu:
Menu Text
Command Name
ID
Edit Constant
ID_COMPONENT_EDIT_CONSTANT
32336
Align Tree Left
ID_COMPONENT_LEFTALIGNTREE
32338
Align Tree Right
ID_COMPONENT_RIGHTALIGNTREE
32340
Change Root Element
ID_COMPONENT_CHANGEROOTELEMENT
32334
Edit Schema Definition in XMLSpy
ID_COMPONENT_EDIT_SCHEMA
32337
Duplicate Input
ID_COMPONENT_CREATE_DUPLICATE_ICON
32335
Remove Duplicate
ID_COMPONENT_REMOVE_DUPLICATE_ICON
32339
Database Table Actions
ID_POPUP_DATABASETABLEACTIONS
32400
Database Key Settings
ID_POPUP_VALUEKEYSETTINGS
32417
Component Settings...
ID_COMPONENT_SETTINGS
32341
© 2008 Altova GmbH
Altova MapForce 2008
286
MapForceControl
Command Table
12.3.6 Connection Menu
Commands from the Connection menu:
Menu Text
Menu Text
ID
Auto Connect Matching Children
ID_CONNECTION_AUTOCONNECTCHILDREN
32342
Settings for Connect Matching Children...
ID_CONNECTION_SETTINGS
32344
Connect Matching Children
ID_CONNECTION_MAPCHILDELEMENTS
32343
Standard Mapping (target driven)
ID_POPUP_NORMALCONNECTION
32401
Source-driven Mapping (mixed-content)
ID_POPUP_ORDERBYSOURCECONNECTION
32403
Connection Settings...
ID_POPUP_CONNECTION_SETTINGS
32398
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
Command Table
287
12.3.7 Function Menu
Commands from the Function menu:
Menu Text
Command Name
ID
Create User-Defined Function...
ID_FUNCTION_CREATE_EMPTY
32380
Create User-Defined Function From
Selection...
ID_FUNCTION_CREATE_FROM_SELECTION
32381
Function Settings...
ID_FUNCTION_SETTINGS
32387
Insert Input
ID_FUNCTION_INSERT_INPUT
32383
Insert Output...
ID_FUNCTION_INSERT_OUTPUT
32402
© 2008 Altova GmbH
Altova MapForce 2008
288
MapForceControl
Command Table
12.3.8 Output Menu
Commands from the Output menu:
Menu Text
Command Name
ID
XSLT 1.0
ID_SELECT_LANGUAGE_XSLT
32433
XSLT 2.0
ID_SELECT_LANGUAGE_XSLT2
32434
XQuery
ID_SELECT_LANGUAGE_XQUERY
32432
Java
ID_SELECT_LANGUAGE_JAVA
32431
C# (Sharp)
ID_SELECT_LANGUAGE_CSHARP
32430
C++
ID_SELECT_LANGUAGE_CPP
32429
Validate output XML file
ID_XML_VALIDATE
32458
Save Output File...
IDC_FILE_SAVEGENERATEDOUTPUT
32321
Run SQL-script
ID_TRANSFORM_RUN_SQL
32442
Insert/Remove Bookmark
ID_TOGGLE_BOOKMARK
32317
Next Bookmark
ID_GOTONEXTBOOKMARK
32315
Previous Bookmark
ID_GOTOPREVBOOKMARK
32314
Remove All Bookmarks
ID_REMOVEALLBOOKMARKS
32313
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
Command Table
289
12.3.9 View Menu
Commands from the View menu:
Menu Text
Command Name
ID
Show Annotations
ID_SHOW_ANNOTATION
32435
Show Types
ID_SHOW_TYPES
32437
Show Library In Function Header
ID_VIEW_SHOWLIBRARYINFUNCTIONHEADER
32448
Show Tips
ID_SHOW_TIPS
32436
Show selected component
connectors
ID_VIEW_AUTOHIGHLIGHTCOMPONENTCONNECTION 32443
S
Show connectors from source to
target
ID_VIEW_RECURSIVEAUTOHIGHLIGHT
32447
Zoom
ID_VIEW_ZOOM
32451
Status Bar
ID_VIEW_STATUS_BAR
32449
Library Window
ID_VIEW_LIBRARY_WINDOW
32445
Validation Output
ID_VIEW_VALIDATION_OUTPUT
32450
Overview
ID_VIEW_OVERVIEW_WINDOW
32446
Project Window
ID_VIEW_PROJECT_WINDOW
32302
© 2008 Altova GmbH
Altova MapForce 2008
290
MapForceControl
Command Table
12.3.10 Tools Menu
Commands from the Tools menu:
Menu Text
Command Name
ID
Customize...
ID_VIEW_CUSTOMIZE
32444
Options...
ID_TOOLS_OPTIONS
32441
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
Command Table
291
12.3.11 Window Menu
Commands from the Window menu:
Menu Text
Command Name
ID
Close
ID_WINDOW_CLOSE
32453
Close All
ID_WINDOW_CLOSEALL
32454
Cascade
ID_WINDOW_CASCADE
57650
Tile Horizontal
ID_WINDOW_TILE_HORZ
57651
Tile Vertical
ID_WINDOW_TILE_VERT
57652
© 2008 Altova GmbH
Altova MapForce 2008
292
MapForceControl
Command Table
12.3.12 Help Menu
Commands from the Help menu:
Menu Text
Command Name
ID
Table of Contents...
IDC_HELP_CONTENTS
32322
Index..
IDC_HELP_INDEX
32323
Search...
IDC_HELP_SEARCH
32324
Software Activation...
IDC_ACTIVATION
32701
Registration...
IDC_REGISTRATION
32330
Check for Updates...
IDC_CHECK_FOR_UPDATES
32700
Order Form...
IDC_OPEN_ORDER_PAGE
32326
Support Center...
IDC_OPEN_SUPPORT_PAGE
32327
FAQ on the Web...
IDC_SHOW_FAQ
32331
Components Download...
IDC_OPEN_COMPONENTS_PAGE
32325
MapForce on the Internet..
IDC_OPEN_XML_SPY_HOME
32328
MapForce Training...
IDC_OPEN_MAPFORCE_TRAINING_PAGE
32300
About MapForce...
ID_APP_ABOUT
57664
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
Command Table
293
12.3.13 Commands not in Main Menu
Commands not in the main menu:
Menu Text
Command Name
ID
IDC_QUICK_HELP
32329
Edit FlexText Configuration
ID_COMPONENT_EDIT_MFT
32301
Priority Context
ID_COMPONENT_PRIORITYCONTEXT
32318
ID_EDIT_FINDPREV
32350
ID_FUNCTION_GOTO_MAIN
32382
ID_FUNCTION_INSERT_INPUT_AT_POINT
32384
ID_FUNCTION_REMOVE
32385
ID_FUNCTION_REPLACE_WITH_COMPONENTS
32386
ID_MAPFORCEVIEW_ZOOM
32395
ID_NEXT_PANE
32397
Insert Input
Replace component with internal
function structure
Add Active File to Project
ID_POPUP_PROJECT_ADDACTIVEFILETOPROJECT 32405
Add Files to Project...
ID_POPUP_PROJECT_ADDFILESTOPROJECT
32406
C++
ID_POPUP_PROJECT_GENERATECPPCODE
32408
C# (Sharp)
ID_POPUP_PROJECT_GENERATECSCODE
32409
Java
ID_POPUP_PROJECT_GENERATEJAVACODE
32410
XQuery
ID_POPUP_PROJECT_GENERATEXQUERY
32411
XSLT 1.0
ID_POPUP_PROJECT_GENERATEXSLT
32412
XSLT 2.0
ID_POPUP_PROJECT_GENERATEXSLT2
32413
Generate All
ID_POPUP_PROJECT_GENERATE_ALL
32303
Generate code in default language
ID_POPUP_PROJECT_GENERATE_CODE
32414
Open
ID_POPUP_PROJECT_OPEN_MAPPING
32307
Properties...
ID_POPUP_PROJECT_PROJECTPROPERTIES
32428
Remove
ID_POPUP_PROJECT_REMOVE
32308
ID_PREV_PANE
32418
ID_TOGGLE_FOLDINGMARGIN
32438
ID_TOGGLE_INDENTGUIDES
32439
ID_TOGGLE_NUMLINEMARGIN
32440
ID_WORD_WRAP
32457
© 2008 Altova GmbH
Altova MapForce 2008
294
MapForceControl
12.4
Accessing MapForce API
Accessing MapForce API
The focus of this documentation is the ActiveX controls and interfaces required to integrate the
MapForce user interface into your application. To allow you to automate or control the
functionality of the integrated components, the following properties give you access to the
MapForce automation interface (MapForce API):
MapForceControl.Application
MapForceControlDocument.Document
MapForceControlPlaceHolder.Project
Some restrictions apply to the usage of the MapForce automation interface when integrating
MapForceControl at document-level. See Integration at document level for details.
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
12.5
Object Reference
295
Object Reference
Objects:
MapForceCommand
MapForceCommands
MapForceControl
MapForceControlDocument
MapForceControlPlaceHolder
To give access to standard MapForce functionality, objects of the MapForce automation
interface can be accessed as well. See MapForceControl.Application,
MapForceControlDocument.Document and MapForceControlPlaceHolder.Project for more
information.
© 2008 Altova GmbH
Altova MapForce 2008
296
MapForceControl
Object Reference
12.5.1 MapForceCommand
Properties:
ID
Label
IsSeparator
ToolTip
StatusText
Accelerator
SubCommands
Description:
Each MapForceCommand object can be one of three possible types:



Command: ID is set to a value greater 0 and Label is set to the command name.
IsSeparator is false and the SubCommands collection is empty.
Separator: IsSeparator is true. ID is 0 and Label is not set. The SubCommands
collection is empty.
(Sub) Menu: The SubCommands collection contains MapForceCommand objects and
Label is the name of the menu. ID is set to 0 and IsSeparator is false.
Accelerator
Property: Label as string
Description:
For command objects that are children of the ALL_COMMANDS collection, this is the
accelerator key defined for the command. If the command has no accelerator key assigned, this
property returns the empty string.
The string representation of the accelerator key has the following format:
[ALT+][CTRL+][SHIFT+]key
Where key is converted using the Windows Platform SDK function GetKeyNameText.
ID
Property: ID as long
Description:
ID is 0 for separators and menus.
For commands, this is the ID which can be used with Exec and QueryStatus.
IsSeparator
Property: IsSeparator as boolean
Description:
True if the command is a separator.
Label
Property: Label as string
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
Object Reference
297
Description:
Label is empty for separators.
For command objects that are children of the ALL_COMMANDS collection, this is a unique
name. Command icons are stored in files with this name. See Query MapForceCommands for
more information.
For command objects that are children of menus, the label property holds the command's menu
text.
For sub-menus, this property holds the menu text.
StatusText
Property: Label as string
Description:
For command objects that are children of the ALL_COMMANDS collection, this is the text
shown in the status bar when the command is selected.
SubCommands
Property: SubCommands as MapForceCommands
Description:
The SubCommands collection holds any sub-commands if this command is actually a menu or
submenu.
ToolTip
Property: ToolTip as string
Description:
For command objects that are children of the ALL_COMMANDS collection, this is the text
shown as tool-tip.
© 2008 Altova GmbH
Altova MapForce 2008
298
MapForceControl
Object Reference
12.5.2 MapForceCommands
Properties:
Count
Item
Description:
Collection of MapForceCommand objects to get access to command labels and IDs of the
MapForceControl. Those commands can be executed with the Exec method and their status
can be queried with QueryStatus.
Count
Property: Count as long
Description:
Number of MapForceCommand objects on this level of the collection.
Item
Property: Item (n as long) as MapForceCommand
Description:
Gets the command with the index n in this collection. Index is 1-based.
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
Object Reference
299
12.5.3 MapForceControl
Properties:
IntegrationLevel
Appearance
Application
BorderStyle
CommandsList
CommandsStructure (deprecated)
EnableUserPrompts
MainMenu
ReadOnly
Toolbars
Methods:
Open
Exec
QueryStatus
Events:
OnCloseEditingWindow
OnContextChanged
OnDocumentOpened
OnFileChangedAlert
OnLicenseProblem
OnOpenedOrFocused
OnUpdateCmdUI
OnProjectOpened
This object is a complete ActiveX control and should only be visible if the MapForce library is
used in the Application Level mode.
CLSID: A38637E9-5759-4456-A167-F01160CC22C1
ProgID: Altova.MapForceControl
Properties
The following properties are defined:
IntegrationLevel
ReadOnly
EnableUserPrompts
Appearance
BorderStyle
Command related properties:
CommandsList
MainMenu
Toolbars
CommandsStructure (deprecated)
Access to MapForceAPI:
Application
Appearance
Property: Appearance as short
Dispatch Id: -520
© 2008 Altova GmbH
Altova MapForce 2008
300
MapForceControl
Object Reference
Description:
A value not equal to 0 displays a client edge around the control. Default value is 0.
Application
Property: Application as Application
Dispatch Id: 4
Description:
The Application property gives access to the Application object of the complete
MapForce automation server API. The property is read-only.
BorderStyle
Property: BorderStyle as short
Dispatch Id: -504
Description:
A value of 1 displays the control with a thin border. Default value is 0.
CommandsList
Property: CommandList as MapForceCommands (read-only)
Dispatch Id: 1004
Description:
This property returns a flat list of all commands defined available with MapForceControl. For
more information see C# Sample.
CommandsStructure (deprecated)
Property: CommandsStructure as MapForceCommands (deprecated)
Dispatch Id: 3
Remark:
This property is deprecated. Instead, use CommandsList, MainMenu, Toolbars.
Description:
The CommandsStructure collection contains all commands of the MapForceControl as
MapForceCommand objects. At the first level of the collection two special MapForceCommand
objects with the following labels are accessible:


IDR_MAPFORCE: This object holds all commands as hierarchical menu structure.
ALL_COMMANDS: This object holds all commands in a flat list.
Sample:
C# code to access the first level of the collection.
MapForceCommands objCommands;
objCommands = axMapForceControl.CommandsStructure;
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
Object Reference
301
long nCount = objCommands.Count;
for(long idx = 0;idx < nCount;idx++)
{
MapForceCommand objCommand;
objCommand = objCommands[(int)idx];
// We are looking for the Menu with the name IDR_MAPFORCE. This
menu should contain
// the complete main menu of MapForce.
if(objCommand.Label == "IDR_MAPFORCE")
{
// read menu structure here...
}
if(objCommand.Label == "ALL_COMMANDS")
{
// read all commands here...
}
}
EnableUserPrompts
Property: EnableUserPrompts as boolean
Dispatch Id: 1006
Description:
Setting this property to false, disables user prompts in the control. The default value is true.
IntegrationLevel
Property: IntegrationLevel as ICActiveXIntegrationLevel
Dispatch Id: 1000
Description:
The IntegrationLevel property determines the operation mode of the control. See also
Integration at the application level and Integration at document level for more information.
Note: It is important to set this property immediately after the creation of the
MapForceControl object.
MainMenu
Property: MainMenu as MapForceCommand (read-only)
Dispatch Id: 1003
Description:
This property gives access to the description of the MapForceControl main menu. For more
information see C# Sample.
© 2008 Altova GmbH
Altova MapForce 2008
302
MapForceControl
Object Reference
ReadOnly
Property: ReadOnly as boolean
Dispatch Id: 2
Description:
Using this property you can turn on and off the read-only mode of the control. If ReadOnly is
true it is not possible to modify any document loaded. This property is only used in the
Application-level integration mode.
Toolbars
Property: Toolbars as MapForceCommands (read-only)
Dispatch Id: 1005
Description:
This property returns a list of all toolbar descriptions that describe all toolbars available with
MapForceControl. For more information see C# Sample.
Methods
The following methods are defined:
Open
Exec
QueryStatus
Exec
Method: Exec (nCmdID as long) as boolean
Dispatch Id: 6
Description:
Exec calls the MapForce command with the ID nCmdID. If the command can be executed, the
method returns true. See also CommandsStructure to get a list of all available commands
and QueryStatus to retrieve the status of any command.
Open
Method: Open (strFilePath as string) as boolean
Dispatch Id: 5
Description:
The result of the method depends on the extension passed in the argument strFilePath. If
the file extension is .mfd, a new document is opened. If the file extension is .mfp, the
corresponding project is opened. If a different file extension is passed into the method, the
control tries to load the file as a new component into the active document.
Do not use this method to load documents or projects when using the control in document-level
integration mode. Instead, use MapForceControlDocument.OpenDocument and
MapForceControlPlaceHolder.OpenProject.
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
Object Reference
303
QueryStatus
Method: QueryStatus (nCmdID as long) as long
Dispatch Id: 7
Description:
QueryStatus returns the enabled/disabled and checked/unchecked status of the command
specified by nCmdID. The status is returned as a bit mask.
Bit
Value
Name
Meaning
----------------------------------------------------------------------------------------------------------------------0
1
Supported
Set if the command is supported.
1
2
Enabled
Set if the command is enabled (can be
executed).
2
4
Checked
Set if the command is checked.
This means that if QueryStatus returns 0 the command ID is not recognized as a valid
MapForce command. If QueryStatus returns a value of 1 or 5, the command is disabled.
Events
The MapForceControl ActiveX control provides the following connection point events:
OnCloseEditingWindow
OnContextChanged
OnDocumentOpened
OnFileChangedAlert
OnLicenseProblem
OnOpenedOrFocused
OnUpdateCmdUI
OnProjectOpened
OnCloseEditingWindow
Event: OnCloseEditingWindow (i_strFilePath as String) as boolean
Dispatch Id: 1002
Description:
This event gets triggered when MapForce needs to close an already open document. As an
answer to this event, clients should close the editor window associated with i_strFilePath.
Returning true from this event indicates that the client has closed the document. Clients can
return false if no specific handling is required and MapForceControl should try to close the
editor and destroy the associated document control.
OnContextChanged
Event: OnContextChanged (i_strContextName as String, i_bActive as bool) as bool
Dispatch Id: 1004
© 2008 Altova GmbH
Altova MapForce 2008
304
MapForceControl
Object Reference
Description:
This event is not used in MapForce.
OnDocumentOpened
Event: OnDocumentOpened (objDocument as Document)
Dispatch Id: 3
Description:
This event gets triggered whenever a document gets opened. The argument objDocument is
a Document object from the MapForce automation interface and can be used to query more
details on the document or perform additional operations. When integrating on document-level it
is often better to use the event MapForceControlDocument.OnDocumentOpened instead.
OnFileChangedAlert
Event: OnFileChangedAlert (i_strFilePath as String) as bool
Dispatch Id: 1001
Description:
This event is triggered when a file loaded with MapForce, is changed on the harddisk by another
application. Clients should return true, if they handled the event, or false, if MapForce should
handle it in its customary way, i.e. prompting the user for reload.
OnLicenseProblem
Event: OnLicenseProblem (i_strLicenseProblemText as String)
Dispatch Id: 1005
Description:
This event is triggered when MapForce detects that no valid license is available for this control.
In case of restricted user licenses this can happen some time after the control has been
initialized. Integrators should use this event to disable access to this control's functionality. After
returning from this event, the control will block access to its functionality (e.g. show empty
windows in its controls and return errors on requests).
OnOpenedOrFocused
Event: OnOpenedOrFocused (i_strFilePath as String, i_bOpenWithThisControl as
bool)
Dispatch Id: 1000
Description:
When integrating at application level, this event informs clients that a document has been
opened, or made active by MapForce.
When integrating at document level, this event instructs the client to open the file
i_strFilePath in a document window. If the file is already open, the corresponding
document window should be made the active window.
if i_bOpenWithThisControl is true, the document must be opened withMapForceControl,
since internal access is required. Otherwise, the file can be opened with different editors.
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
Object Reference
305
OnProjectOpened
Event: OnProjectOpened (objProject as Project)
Dispatch Id: 2
Description:
This event gets triggered whenever a project is opened. The argument objProjectDocument
is a Project object from the MapForce automation interface and can be used to query more
details on the project or perform additional operations.
OnUpdateCmdUI
Event: OnUpdateCmdUI ()
Dispatch Id: 1003
Description:
Called frequently to give integrators a good opportunity to check status of MapForce commands
using MapForceControl.QueryStatus. Do not perform long operations in this callback.
© 2008 Altova GmbH
Altova MapForce 2008
306
MapForceControl
Object Reference
12.5.4 MapForceControlDocument
Properties:
Appearance
BorderStyle
Document
IsModified
Path
ReadOnly
ZoomLevel
Methods:
Exec
New
Open
QueryStatus
Reload
Save
SaveAs
Events:
OnActivate
OnClosed
OnContextChanged
OnDocumentSaveAs
OnFileChangedAlert
OnModifiedFlagChanged
OnOpened
OnSetEditorTitle
If the MapForceControl is integrated in the Document Level mode each document is displayed
in an own object of type MapForceControlDocument. The MapForceControlDocument
contains only one document at the time but can be reused to display different files one after
another.
This object is a complete ActiveX control.
CLSID: DFBB0871-DAFE-4502-BB66-08CEB7DF5255
ProgID: Altova.MapForceControlDocument
Properties
The following properties are defined:
ReadOnly
IsModified
ZoomLevel
Path
Appearance
BorderStyle
Access to MapForceAPI:
Document
Appearance
Property: Appearance as short
Dispatch Id: -520
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
Object Reference
307
Description:
A value not equal to 0 displays a client edge around the document control. Default value is 0.
BorderStyle
Property: BorderStyle as short
Dispatch Id: -504
Description:
A value of 1 displays the control with a thin border. Default value is 0.
Document
Property: Document as Document
Dispatch Id: 3
Description:
The Document property gives access to the Document object of the MapForce automation
server API. This interface provides additional functionalities which can be used with the
document loaded in the control. The property is read-only.
IsModified
Property: IsModified as boolean (read-only)
Dispatch Id: 1006
Description:
IsModified is true if the document content has changed since the last open, reload or save
operation. It is false, otherwise.
Path
Property: Path as String
Dispatch Id: 1005
Description:
Sets or gets the full path name of the document loaded into the control.
ReadOnly
Property: ReadOnly as boolean
Dispatch Id: 1007
Description:
Using this property you can turn on and off the read-only mode of the document. If ReadOnly
is true it is not possible to do any modifications.
© 2008 Altova GmbH
Altova MapForce 2008
308
MapForceControl
Object Reference
ZoomLevel
Property: ZoomLevel as long
Dispatch Id: 2
Description:
The ZoomLevel property allows to set the Mapping view magnification in a range from 1 to
100. A ZoomLevel of 50 is the default and shows the view content at normal size.
Methods
The following methods are defined:
Document handling:
New
Open
Reload
Save
SaveAs
OpenDocument (deprecated)
NewDocument (deprecated)
SaveDocument (deprecated)
Command Handling:
Exec
QueryStatus
Exec
Method: Exec (nCmdID as long) as boolean
Dispatch Id: 8
Description:
Exec calls the MapForce command with the ID nCmdID. If the command can be executed, the
method returns true. The client should call the Exec method of the document control if there is
currently an active document available in the application.
See also CommandsStructure to get a list of all available commands and QueryStatus to
retrieve the status of any command.
New
Method: New () as boolean
Dispatch Id: 1000
Description:
This method initializes a new mapping inside the control..
NewDocument (deprecated)
Method: NewDocument () as boolean (deprecated)
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
Object Reference
309
Description:
The method resets the content of the MapForceControlDocument object to a new empty
document. Please use the Path property to set path and filename. Otherwise the control can't
save the document using SaveDocument.
Open
Method: Open (strFileName as string) as boolean
Dispatch Id: 1001
Description:
Open loads the file strFileName as the new document into the control.
OpenDocument (deprecated)
Method: OpenDocument (strFileName as string) as boolean (deprecated)
Description:
OpenDocument loads the file strFileName as the new document into the control.
QueryStatus
Method: QueryStatus (nCmdID as long) as long
Dispatch Id: 9
Description:
QueryStatus returns the enabled/disabled and checked/unchecked status of the command
specified by nCmdID. The status is returned as a bit mask.
Bit
Value
Name
Meaning
----------------------------------------------------------------------------------------------------------------------0
1
Supported
Set if the command is supported.
1
2
Enabled
Set if the command is enabled (can be
executed).
2
4
Checked
Set if the command is checked.
This means that if QueryStatus returns 0 the command ID is not recognized as a valid
MapForce command. If QueryStatus returns a value of 1 or 5 the command is disabled. The
client should call the QueryStatus method of the document control if there is currently an
active document available in the application.
Reload
Method: Reload () as boolean
Dispatch Id: 1002
Description:
Reload updates the document content from the file system.
© 2008 Altova GmbH
Altova MapForce 2008
310
MapForceControl
Object Reference
Save
Method: Save () as boolean
Dispatch Id: 1003
Description:
Save saves the current document at the location Path.
SaveAs
Method: OpenDocument (strFileName as string) as boolean
Dispatch Id: 1004
Description:
SaveAs sets Path to strFileName and then saves the document to this location.
SaveDocument (deprecated)
Method: SaveDocument () as boolean (deprecated)
Description:
SaveDocument saves the current document at the location Path.
Events
The MapForceControlDocument ActiveX control provides following connection point events:
OnActivate
OnClosed
OnContextChanged
OnDocumentSaveAs
OnFileChangedAlert
OnModifiedFlagChanged
OnOpened
OnSetEditorTitle
OnDocumentClosed (deprecated)
OnDocumentOpened (deprecated)
OnActivate
Event: OnActivate ()
Dispatch Id: 1005
Description:
This event is triggered when the document control is activated, has the focus, and is ready for
user input.
OnClosed
Event: OnClosed ()
Dispatch Id: 1001
Description:
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
Object Reference
311
This event gets triggered whenever the document loaded into this control gets closed. The
property Document gives you access to this document, but it should be used with care.
OnContextChanged
Event: OnContextChanged (i_strContextName as String, i_bActive as bool) as bool
Dispatch Id: 1004
Description:
This event is triggered when this document is shown in a different MapForce view. The following
values are passed:




Mapping view - "View_0" is passed as the context name
Algorithm view - "View_1" is passed as the context name
DB Query view - "View_2" is passed as the context name
Output view - "View_3" is passed as the context name
OnDocumentClosed (deprecated)
Event: OnDocumentClosed (objDocument as Document) (deprecated)
Dispatch Id: 2
Remark:
This property is deprecated. Instead, use OnClosed.
Description:
This event gets triggered whenever the document loaded into this control gets closed. The
argument objDocument is a Document object from the MapForce automation interface and
should be used with care.
OnDocumentOpened (deprecated)
Event: OnDocumentOpened (objDocument as Document) (deprecated)
Dispatch Id: 1
Remark:
This property is deprecated. Instead, use OnOpened.
Description:
This event gets triggered whenever a document gets opened in this control. The argument
objDocument is a Document object from the MapForce automation interface and can be used
to query more details about the document or perform additional operations.
OnDocumentSaveAs
Event: OnContextDocumentSaveAs (i_strFileName as String)
Dispatch Id: 1007
Description:
This event is triggered when this document gets internally saved under a new name.
© 2008 Altova GmbH
Altova MapForce 2008
312
MapForceControl
Object Reference
OnFileChangedAlert
Event: OnFileChangedAlert () as bool
Dispatch Id: 1003
Description:
This event is triggered when the file loaded into this document control, is changed on the
harddisk by another application. Clients should return true, if they handled the event, or false, if
MapForce should handle it in its customary way, i.e. prompting the user for reload.
OnModifiedFlagChanged
Event: OnModifiedFlagChanged (i_bIsModified as boolean)
Dispatch Id: 3
Description:
This event gets triggered whenever the document changes between modified and unmodified
state. The parameter i_bIsModifed is true if the document contents differs from the original
content, and false, otherwise.
OnOpened
Event: OnOpened ()
Dispatch Id: 1000
Description:
This event gets triggered whenever a document gets opened in this control. The property
Document gives you access to this document.
OnSetEditorTitle
Event: OnSetEditorTitle ()
Dispatch Id: 1006
Description:
This event is being raised when the contained document is being internally renamed.
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
Object Reference
313
12.5.5 MapForceControlPlaceHolder
Properties available for all kinds of placeholder windows:
PlaceholderWindowID
Properties for project placeholder window:
Project
Methods for project placeholder window:
OpenProject
Events for project placeholder window:
OnModifiedFlagChanged
OnSetLabel
The MapForceControlPlaceHolder control is used to show the additional MapForce
windows like Overview, Library or Project window. It is used like any other ActiveX control and
can be placed anywhere in the client application.
CLSID: FDEC3B04-05F2-427d-988C-F03A85DE53C2
ProgID: Altova.MapForceControlPlaceHolder
Properties
The following properties are defined:
PlaceholderWindowID
Access to MapForceAPI:
Project
Label
Property: Label as String (read-only)
Dispatch Id: 1001
Description:
This property gives access to the title of the placeholder. The property is read-only.
PlaceholderWindowID
Property: PlaceholderWindowID as MapForceControlPlaceholderWindow
Dispatch Id: 1000
Description:
Using this property the object knows which MapForce window should be displayed in the client
area of the control. The PlaceholderWindowID can be set at any time to any valid value of
the MapForceControlPlaceholderWindow enumeration. The control changes its state
immediately and shows the new MapForce window.
Project
Property: Project as Project (read-only)
© 2008 Altova GmbH
Altova MapForce 2008
314
MapForceControl
Object Reference
Dispatch Id: 2
Description:
The Project property gives access to the Project object of the MapForce automation server
API. This interface provides additional functionalities which can be used with the project loaded
into the control. The property will return a valid project interface only if the placeholder window
has PlaceholderWindowID with a value of MapForceXProjectWindow (=3). The
property is read-only.
Methods
The following method is defined:
OpenProject
OpenProject
Method: OpenProject (strFileName as string) as boolean
Dispatch Id: 3
Description:
OpenProject loads the file strFileName as the new project into the control. The method will
fail if the placeholder window has a PlaceholderWindowID different to
MapForceXProjectWindow (=3).
Events
The MapForceControlPlaceholder ActiveX control provides following connection point events:
OnModifiedFlagChanged
OnSetLabel
OnModifiedFlagChanged
Event: OnModifiedFlagChanged (i_bIsModified as boolean)
Dispatch Id: 1
Description:
This event gets triggered only for placeholder controls with a PlaceholderWindowID of
MapForceXProjectWindow (=3). Th event is fired whenever the project content changes
between modified and unmodified state. The parameter i_bIsModifed is true if the project
contents differs from the original content, and false, otherwise.
OnSetLabel
Event: OnSetLabel (i_strLabel as String)
Dispatch Id: 1000
Description:
This event gets triggered whenever the label on a placeholder control window should be
changed.
Altova MapForce 2008
© 2008 Altova GmbH
MapForceControl
Object Reference
315
12.5.6 Enumerations
The following enumerations are defined:
ICActiveXIntegrationLevel
MapForceControlPlaceholderWindow
ICActiveXIntegrationLevel
Possible values for the IntegrationLevel property of the MapForceControl.
ICActiveXIntegrationOnApplicationLevel
ICActiveXIntegrationOnDocumentLevel
= 0
= 1
MapForceControlPlaceholderWindow
This enumeration contains the list of the supported additional MapForce windows.
MapForceXNoWindow
MapForceXLibraryWindow
MapForceXOverviewWindow
MapForceXValidationWindow
MapForceXProjectWindow
© 2008 Altova GmbH
=
=
=
=
=
-1
0
1
2
3
Altova MapForce 2008
Chapter 13
Appendices
318
Appendices
13
Appendices
These appendices contain technical information about MapForce and important licensing
information. Each appendix contains sub-sections as given below:
Technical Data






OS and memory requirements
Altova XML Parser
Altova XSLT and XQuery Engines
Unicode support
Internet usage
License metering
License Information



Electronic software distribution
Copyrights
End User License Agreement
Altova MapForce 2008
© 2008 Altova GmbH
Appendices
13.1
Engine information
319
Engine information
This section contains information about implementation-specific features of the Altova XML
Validator, Altova XSLT 1.0 Engine, Altova XSLT 2.0 Engine, and Altova XQuery Engine.
© 2008 Altova GmbH
Altova MapForce 2008
320
Appendices
Engine information
13.1.1 XSLT 1.0 Engine: Implementation Information
The Altova XSLT 1.0 Engine is built into Altova's XMLSpy, StyleVision, Authentic, and
MapForce XML products. It is also available in the free AltovaXML package. The Altova XSLT
1.0 Engine implements and conforms to the World Wide Web Consortium's XSLT 1.0
Recommendation of 16 November 1999 and XPath 1.0 Recommendation of 16 November 1999
. Limitations and implementation-specific behavior are listed below.
Limitations


The xsl:preserve-space and xsl:strip-space elements are not supported.
When the method attribute of xsl:output is set to HTML, or if HTML output is
selected by default, then special characters in the XML or XSLT file are inserted in the
HTML document directly as special characters; they are not inserted as HTML
character references in the output. For instance, the character &#160; (the decimal
character reference for a non-breaking space) is not inserted as &nbsp; in the HTML
code, but directly as a non-breaking space.
Implementation's handling of whitespace-only nodes in source XML document
The XML data (and, consequently, the XML Infoset) that is passed to the Altova XSLT 1.0
Engine is stripped of boundary-whitespace-only text nodes. (A boundary-whitespace-only text
node is a child whitespace-only text node that occurs between two elements within an element
of mixed content.) This stripping may have an effect on the value returned by the
fn:position(), fn:last(), and fn:count() functions.
For any node selection that selects text nodes also, boundary-whitespace-only text nodes would
typically also be included in the selection. However, since the XML Infoset used by the Altova
engines has boundary-whitespace-only text nodes stripped from it, these nodes are not present
in the XML Infoset. As a result, the size of the selection and the numbering of nodes in the
selection will be different than that for a selection which included these text nodes. The
fn:position(), fn:last(), and fn:count() functions, therefore, could produce results
that are different from those produced by some other processors.
A situation in which boundary-whitespace-only text nodes are evaluated as siblings of other
elements arises most commonly when xsl:apply-templates is used to apply templates.
When the fn:position(), fn:last(), and fn:count() functions are used in patterns with
a name test (for example, para[3], which is short for para[position()=3]),
boundary-whitespace-only nodes are irrelevant since only the named elements (para in the
above example) are selected. (Note, however, that boundary-whitespace-only nodes are
relevant in patterns that use the wildcard, for example, *[10].)
Note: If a boundary-whitespace-only text node is required in the output, then insert the required
whitespace within one of the two adjoining child elements. For example, the XML fragment:
<para>This is <b>bold</b> <i>italic</>.</para>
when processed with the XSLT template
<xsl:template match="para">
<xsl:apply-templates/>
</xsl:template>
will produce:
This is bolditalic.
To get a space between bold and italic in the output, insert a space character within either
Altova MapForce 2008
© 2008 Altova GmbH
Appendices
Engine information
321
the <b> or <i> elements in the XML source. For example:
<para>This is <b>bold</b> <i> italic</>.</para> or
<para>This is <b>bold&#x20;</b> <i>italic</>.</para> or
<para>This is <b>bold</b><i>&#x20;italic</>.</para>
When such an XML fragment is processed with the same XSLT template given above, it will
produce:
This is bold italic.
© 2008 Altova GmbH
Altova MapForce 2008
322
Appendices
Engine information
13.1.2 XSLT 2.0 Engine: Implementation Information
The Altova XSLT 2.0 Engine is built into Altova's XMLSpy, StyleVision, Authentic, and
MapForce XML products. It is also available in the free AltovaXML package. This section
describes the engine's implementation-specific aspects of behavior. It starts with a section
giving general information about the engine, and then goes on to list the implementation-specific
behavior of XSLT 2.0 functions.
For information about implementation-specific behavior of XPath 2.0 functions, see the section,
XPath 2.0 and XQuery 1.0 Functions.
General Information
The Altova XSLT 2.0 Engine conforms to the World Wide Web Consortium's (W3C's) XSLT
2.0 Recommendation of 23 January 2007. Note the following general information about the
engine.
Backwards Compatibility
The Altova XSLT 2.0 Engine is backwards compatible. The only time the backwards
compatibility of the XSLT 2.0 Engine comes into play is when using the XSLT 2.0 Engine of
Altova XML to process an XSLT 1.0 stylesheet. Note that there could be differences in the
outputs produced by the XSLT 1.0 Engine and the backwards-compatible XSLT 2.0 Engine.
In all other Altova products, the backwards-compatibility issue never arises. This is because
these products automatically select the appropriate engine for the transformation. For example,
consider that in XMLSpy you specify that a certain XML document be processed with an XSLT
1.0 stylesheet. When the transformation command is invoked, XMLSpy automatically selects
the XSLT 1.0 Engine of XMLSpy to carry out the transformation.
Note:
The stylesheet version is specified in the version attribute of the stylesheet or
transform element of the stylesheet.
Namespaces
Your XSLT 2.0 stylesheet should declare the following namespaces in order for you to be able
to use the type constructors and functions available in XSLT 2.0. The prefixes given below are
conventionally used; you could use alternative prefixes if you wish.
Namespace Name Prefix
Namespace URI
XML Schema types xs:
http://www.w3.org/2001/XMLSchema
XPath 2.0 functions fn:
http://www.w3.org/2005/xpath-functions
Typically, these namespaces will be declared on the xsl:stylesheet or xsl:transform
element, as shown in the following listing:
<xsl:stylesheet version="2.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:fn="http://www.w3.org/2005/xpath-functions"
...
</xsl:stylesheet>
The following points should be noted:

The Altova XSLT 2.0 Engine uses the XPath 2.0 and XQuery 1.0 Functions namespace
Altova MapForce 2008
© 2008 Altova GmbH
Appendices
Engine information



323
(listed in the table above) as its default functions namespace. So you can use XPath
2.0 and XSLT 2.0 functions in your stylesheet without any prefix. If you declare the
XPath 2.0 Functions namespace in your stylesheet with a prefix, then you can
additionally use the prefix assigned in the declaration.
When using type constructors and types from the XML Schema namespace, the prefix
used in the namespace declaration must be used when calling the type constructor (for
example, xs:date).
With the CRs of 23 January 2007, the untypedAtomic and duration datatypes (
dayTimeDuration and yearMonthDuration), which were formerly in the XPath
Datatypes namespace (typically prefixed xdt:) have been moved to the XML Schema
namespace.
Some XPath 2.0 functions have the same name as XML Schema datatypes. For
example, for the XPath functions fn:string and fn:boolean there exist XML
Schema datatypes with the same local names: xs:string and xs:boolean. So if
you were to use the XPath expression string('Hello'), the expression evaluates
as fn:string('Hello')—not as xs:string('Hello').
Schema-awareness
The Altova XSLT 2.0 Engine is schema-aware.
Whitespace in XML document
By default, the Altova XSLT 2.0 Engine strips all boundary whitespace from
boundary-whitespace-only nodes in the source XML document. The removal of this whitespace
affects the values that the fn:position(), fn:last(), fn:count(), and
fn:deep-equal() functions return. For more details, see Whitespace-only Nodes in XML
Document in the XPath 2.0 and XQuery 1.0 Functions section.
Note: If a boundary-whitespace-only text node is required in the output, then insert the required
whitespace within one of the two adjoining child elements. For example, the XML fragment:
<para>This is <b>bold</b> <i>italic</>.</para>
when processed with the XSLT template
<xsl:template match="para">
<xsl:apply-templates/>
</xsl:template>
will produce:
This is bolditalic.
To get a space between bold and italic in the output, insert a space character within either
the <b> or <i> elements in the XML source. For example:
<para>This is <b>bold</b> <i> italic</>.</para> or
<para>This is <b>bold&#x20;</b> <i>italic</>.</para> or
<para>This is <b>bold</b><i>&#x20;italic</>.</para>
When such an XML fragment is processed with the same XSLT template given above, it will
produce:
This is bold italic.
XSLT 2.0 elements and functions
Limitations and implementation-specific behavior of XSLT 2.0 elements and functions are listed
© 2008 Altova GmbH
Altova MapForce 2008
324
Appendices
Engine information
in the section XSLT 2.0 Elements and Functions.
XPath 2.0 functions
Implementation-specific behavior of XPath 2.0 functions is listed in the section XPath 2.0 and
XQuery 1.0 Functions.
XSLT 2.0 Elements and Functions
Limitations
The xsl:preserve-space and xsl:strip-space elements are not supported.
Implementation-specific behavior
Given below is a description of how the Altova XSLT 2.0 Engine handles
implementation-specific aspects of the behavior of certain XSLT 2.0 functions.
function-available
The function tests for the availability of XSLT 2.0 functions, not for the availability of XPath 2.0
functions.
unparsed-text
The href attribute accepts (i) relative paths for files in the base-uri folder, and (ii) absolute
paths with or without the file:// protocol.
Altova MapForce 2008
© 2008 Altova GmbH
Appendices
13.2
Technical Data
325
Technical Data
This section contains useful background information on the technical aspects of your software.
It is organized into the following sections:





OS and Memory Requirements
Altova XML Parser
Altova XSLT and XQuery Engines
Unicode Support
Internet Usage
© 2008 Altova GmbH
Altova MapForce 2008
326
Appendices
Technical Data
13.2.1 OS and Memory Requirements
Operating System
This software application is a 32-bit Windows application that runs on Windows 2000 and
Windows XP.
Memory
Since the software is written in C++ it does not require the overhead of a Java Runtime
Environment and typically requires less memory than comparable Java-based applications.
However, each document is loaded fully into memory so as to parse it completely and to
improve viewing and editing speed. The memory requirement increases with the size of the
document.
Memory requirements are also influenced by the unlimited Undo history. When repeatedly
cutting and pasting large selections in large documents, available memory can rapidly be
depleted.
Altova MapForce 2008
© 2008 Altova GmbH
Appendices
Technical Data
327
13.2.2 Altova XML Parser
When opening any XML document, the application uses its built-in validating parser (the Altova
XML Parser) to check for well-formedness, validate the document against a schema (if
specified), and build trees and Infosets. The Altova XML Parser is also used to provide
intelligent editing help while you edit documents and to dynamically display any validation error
that may occur.
The built-in Altova XML Parser implements the Final Recommendation of the W3C's XML
Schema specification. New developments recommended by the W3C's XML Schema Working
Group are continuously being incorporated in the Altova Parser, so that Altova products give
you a state-of-the-art development environment.
© 2008 Altova GmbH
Altova MapForce 2008
328
Appendices
Technical Data
13.2.3 Altova XSLT and XQuery Engines
Altova products use the Altova XSLT 1.0 Engine, Altova XSLT 2.0 Engine, and Altova XQuery
1.0 Engines. Documentation about implementation-specific behavior for each engine is in the
section Engine Information, in Appendix 1 of the product documentation, should that engine be
used in the product.
These three engines are also available in the AltovaXML package, which can be downloaded
from the Altova website free of charge. Documentation for using the engines is available with
the AltovaXML package.
Altova MapForce 2008
© 2008 Altova GmbH
Appendices
Technical Data
329
13.2.4 Unicode Support
Unicode is the new 16-bit character-set standard defined by the Unicode Consortium that
provides a unique number for every character,
 no matter what the platform,
 no matter what the program,
 no matter what the language.
Fundamentally, computers just deal with numbers. They store letters and other characters by
assigning a number for each one. Before Unicode was invented, there were hundreds of
different encoding systems for assigning these numbers. No single encoding could contain
enough characters: for example, the European Union alone requires several different encodings
to cover all its languages. Even for a single language like English, no single encoding was
adequate for all the letters, punctuation, and technical symbols in common use.
These encoding systems used to conflict with one another. That is, two encodings used the
same number for two different characters, or different numbers for the same character. Any
given computer (especially servers) needs to support many different encodings; yet whenever
data is passed between different encodings or platforms, that data always runs the risk of
corruption.
Unicode is changing all that!
Unicode provides a unique number for every character, no matter what the platform, no matter
what the program, and no matter what the language. The Unicode Standard has been adopted
by such industry leaders as Apple, HP, IBM, JustSystem, Microsoft, Oracle, SAP, Sun, Base
and many others.
Unicode is required by modern standards such as XML, Java, ECMAScript (JavaScript), LDAP,
CORBA 3.0, WML, etc., and is the official way to implement ISO/IEC 10646. It is supported in
many operating systems, all modern browsers, and many other products. The emergence of the
Unicode Standard, and the availability of tools supporting it, are among the most significant
recent global software technology trends.
Incorporating Unicode into client-server or multi-tiered applications and web sites offers
significant cost savings over the use of legacy character sets. Unicode enables a single
software product or a single web site to be targeted across multiple platforms, languages and
countries without re-engineering. It allows data to be transported through many different
systems without corruption.
Windows 2000 and Windows XP
Altova's XML products provide full Unicode support. To edit an XML document, you will also
need a font that supports the Unicode characters being used by that document.
Please note that most fonts only contain a very specific subset of the entire Unicode range and
are therefore typically targeted at the corresponding writing system. Consequently you may
encounter XML documents that contain "unprintable" characters, because the font you have
selected does not contain the required glyphs. Therefore it can sometimes be very useful to
have a font that covers the entire Unicode range - especially when editing XML documents from
all over the world.
The most universal font we have encountered is a typeface called Arial Unicode MS that has
been created by Agfa Monotype for Microsoft. This font contains over 50,000 glyphs and covers
the entire set of characters specified by the Unicode 2.1 standard. It needs 23MB and is
included with Microsoft Office 2000.
© 2008 Altova GmbH
Altova MapForce 2008
330
Appendices
Technical Data
We highly recommend that you install this font on your system and use it with the application if
you are often editing documents in different writing systems. This font is not installed with the
"Typical" setting of the Microsoft Office setup program, but you can choose the Custom Setup
option to install this font.
In the /Examples folder in your application folder you will also find a new XHTML file called
Unicode-UTF8.html that contains the sentence "When the world wants to talk, it speaks
Unicode" in many different languages ("Wenn die Welt miteinander spricht, spricht sie
Unicode") and writing-systems (
) - this line has been
adopted from the 10th Unicode conference in 1997 and is a beautiful illustration of the
importance of Unicode for the XML standard. Opening this file will give you a quick impression
on what is possible with Unicode and what writing systems are supported by the fonts available
on your PC installation.
Right-to-Left Writing Systems
Please note that even under Windows NT 4.0 any text from a right-to-left writing-system (such
as Hebrew or Arabic) is not rendered correctly except in those countries that actually use
right-to-left writing-systems. This is due to the fact that only the Hebrew and Arabic versions of
Windows NT contains support for rendering and editing right-to-left text on the operating system
layer.
Altova MapForce 2008
© 2008 Altova GmbH
Appendices
Technical Data
331
13.2.5 Internet Usage
Altova applications will initiate Internet connections on your behalf in the following situations:





If you click the "Request evaluation key-code" in the Registration dialog (Help |
Software Activation), the three fields in the registration dialog box are transferred to
our web server by means of a regular http (port 80) connection and the free evaluation
key-code is sent back to the customer via regular SMTP e-mail.
If you use the Open URL... dialog box to open a document directly from a URL (File |
Open URL), that document is retrieved through a http (port 80) connection. (This
functionality is available in XMLSpy and Authentic Desktop.)
If you open an XML document that refers to an XML Schema or DTD and the document
is specified through a URL, it is also retrieved through a http (port 80) connection once
you validate the XML document. This may also happen automatically upon opening a
document if you have instructed the application to automatically validate files upon
opening in the File tab of the Options dialog (Tools | Options). (This functionality is
available in XMLSpy and Authentic Desktop.)
If you are using the Send by Mail... command (File | Send by Mail) in XMLSpy, the
current selection or file is sent by means of any MAPI-compliant mail program installed
on the user's PC.
As part of Software Activation and LiveUpdate as further described in this manual and
the Altova Software License Agreement.
© 2008 Altova GmbH
Altova MapForce 2008
332
Appendices
13.3
License Information
License Information
This section contains:



Information about the distribution of this software product
Information about the intellectual property rights related to this software product
The End User License Agreement governing the use of this software product
Please read this information carefully. It is binding upon you since you agreed to these terms
when you installed this software product.
Altova MapForce 2008
© 2008 Altova GmbH
Appendices
License Information
333
13.3.1 Electronic Software Distribution
This product is available through electronic software distribution, a distribution method that
provides the following unique benefits:




You can evaluate the software free-of-charge before making a purchasing decision.
Once you decide to buy the software, you can place your order online at the Altova
website and immediately get a fully licensed product within minutes.
When you place an online order, you always get the latest version of our software.
The product package includes a comprehensive integrated onscreen help system. The
latest version of the user manual is available at www.altova.com (i) in HTML format for
online browsing, and (ii) in PDF format for download (and to print if you prefer to have
the documentation on paper).
30-day evaluation period
After downloading this product, you can evaluate it for a period of up to 30 days free of charge.
About 20 days into this evaluation period, the software will start to remind you that it has not yet
been licensed. The reminder message will be displayed once each time you start the
application. If you would like to continue using the program after the 30-day evaluation period,
you have to purchase an Altova Software License Agreement, which is delivered in the form of
a key-code that you enter into the Software Activation dialog to unlock the product. You can
purchase your license at the online shop at the Altova website.
Helping Others within Your Organization to Evaluate the Software
If you wish to distribute the evaluation version within your company network, or if you plan to
use it on a PC that is not connected to the Internet, you may only distribute the Setup programs,
provided that they are not modified in any way. Any person that accesses the software installer
that you have provided, must request their own 30-day evaluation license key code and after
expiration of their evaluation period, must also purchase a license in order to be able to
continue using the product.
For further details, please refer to the Altova Software License Agreement at the end of this
section.
© 2008 Altova GmbH
Altova MapForce 2008
334
Appendices
License Information
13.3.2 Software Activation and License Metering
As part of Altova’s Software Activation, the software may use your internal network and Internet
connection for the purpose of transmitting license-related data at the time of installation,
registration, use, or update to an Altova-operated license server and validating the authenticity
of the license-related data in order to protect Altova against unlicensed or illegal use of the
software and to improve customer service. Activation is based on the exchange of license
related data such as operating system, IP address, date/time, software version, and computer
name, along with other information between your computer and an Altova license server.
Your Altova product has a built-in license metering module that further helps you avoid any
unintentional violation of the End User License Agreement. Your product is licensed either as a
single-user or multi-user installation, and the license-metering module makes sure that no more
than the licensed number of users use the application concurrently.
This license-metering technology uses your local area network (LAN) to communicate between
instances of the application running on different computers.
Single license
When the application starts up, as part of the license metering process, the software sends a
short broadcast datagram to find any other instance of the product running on another computer
in the same network segment. If it doesn't get any response, it will open a port for listening to
other instances of the application.
Multi license
If more than one instance of the application is used within the same LAN, these instances will
briefly communicate with each other on startup. These instances exchange key-codes in order
to help you to better determine that the number of concurrent licenses purchased is not
accidentally violated. This is the same kind of license metering technology that is common in
the Unix world and with a number of database development tools. It allows Altova customers to
purchase reasonably-priced concurrent-use multi-user licenses.
We have also designed the applications so that they send few and small network packets so as
to not put a burden on your network. The TCP/IP ports (2799) used by your Altova product are
officially registered with the IANA (see
http://www.isi.edu/in-notes/iana/assignments/port-numbers for details) and our license-metering
module is tested and proven technology.
If you are using a firewall, you may notice communications on port 2799 between the computers
that are running Altova products. You are, of course, free to block such traffic between different
groups in your organization, as long as you can ensure by other means, that your license
agreement is not violated.
You will also notice that, if you are online, your Altova product contains many useful functions;
these are unrelated to the license-metering technology.
Altova MapForce 2008
© 2008 Altova GmbH
Appendices
License Information
335
13.3.3 Intellectual Property Rights
The Altova Software and any copies that you are authorized by Altova to make are the
intellectual property of and are owned by Altova and its suppliers. The structure, organization
and code of the Software are the valuable trade secrets and confidential information of Altova
and its suppliers. The Software is protected by copyright, including without limitation by United
States Copyright Law, international treaty provisions and applicable laws in the country in which
it is being used. Altova retains the ownership of all patents, copyrights, trade secrets,
trademarks and other intellectual property rights pertaining to the Software, and that Altova’s
ownership rights extend to any images, photographs, animations, videos, audio, music, text and
"applets" incorporated into the Software and all accompanying printed materials. Notifications of
claimed copyright infringement should be sent to Altova’s copyright agent as further provided on
the Altova Web Site.
Altova software contains certain Third Party Software that is also protected by intellectual
property laws, including without limitation applicable copyright laws as described in detail at
http://www.altova.com/legal_3rdparty.html.
All other names or trademarks are the property of their respective owners.
© 2008 Altova GmbH
Altova MapForce 2008
336
Appendices
License Information
13.3.4 Altova End User License Agreement
THIS IS A LEGAL DOCUMENT -- RETAIN FOR YOUR RECORDS
ALTOVA® END USER LICENSE AGREEMENT
Licensor:
Altova GmbH
Rudolfsplatz 13a/9
A-1010 Wien
Austria
Important - Read Carefully. Notice to User:
This End User License Agreement (“Software License Agreement”) is a legal document
between you and Altova GmbH (“Altova”). It is important that you read this document before
using the Altova-provided software (“Software”) and any accompanying documentation, including,
without limitation printed materials, ‘online’ files, or electronic documentation (“Documentation”).
By clicking the “I accept” and “Next” buttons below, or by installing, or otherwise using the
Software, you agree to be bound by the terms of this Software License Agreement as well as the
Altova Privacy Policy (“Privacy Policy”) including, without limitation, the warranty disclaimers,
limitation of liability, data use and termination provisions below, whether or not you decide to
purchase the Software. You agree that this agreement is enforceable like any written agreement
negotiated and signed by you. If you do not agree, you are not licensed to use the Software, and you
must destroy any downloaded copies of the Software in your possession or control. Please go to our Web
site at http://www.altova.com/eula to download and print a copy of this Software License Agreement for
your files and http://www.altova.com/privacy to review the privacy policy.
1.
SOFTWARE LICENSE
License Grant. Upon your acceptance of this Software License Agreement Altova
(a)
grants you a non-exclusive, non-transferable (except as provided below), limited license to
install and use a copy of the Software on your compatible computer, up to the Permitted Number
of computers. The Permitted Number of computers shall be delineated at such time as you elect
to purchase the Software. During the evaluation period, hereinafter defined, only a single user
may install and use the software on one computer. If you have licensed the Software as part of a
suite of Altova software products (collectively, the “Suite”) and have not installed each product
individually, then the Software License Agreement governs your use of all of the software
included in the Suite. If you have licensed SchemaAgent, then the terms and conditions of this
Software License Agreement apply to your use of the SchemaAgent server software
(“SchemaAgent Server”) included therein, as applicable and you are licensed to use
SchemaAgent Server solely in connection with your use of Altova Software and solely for the
purposes described in the accompanying documentation. In addition, if you have licensed
XMLSpy Enterprise Edition or MapForce Enterprise Edition, or UModel, your license to
install and use a copy of the Software as provided herein permits you to generate source code
based on (i) Altova Library modules that are included in the Software (such generated code
hereinafter referred to as the “Restricted Source Code”) and (ii) schemas or mappings that you
create or provide (such code as may be generated from your schema or mapping source
materials hereinafter referred to as the “Unrestricted Source Code”). In addition to the rights
granted herein, Altova grants you a non-exclusive, non-transferable, limited license to compile
into executable form the complete generated code comprised of the combination of the
Restricted Source Code and the Unrestricted Source Code, and to use, copy, distribute or license
that executable. You may not distribute or redistribute, sublicense, sell, or transfer to a third
party the Restricted Source Code, unless said third party already has a license to the Restricted
Source Code through their separate license agreement with Altova or other agreement with
Altova. Altova reserves all other rights in and to the Software. With respect to the feature(s) of
Altova MapForce 2008
© 2008 Altova GmbH
Appendices
License Information
337
UModel that permit reverse-engineering of your own source code or other source code that you
have lawfully obtained, such use by you does not constitute a violation of this Agreement.
Except as otherwise permitted in Section 1(h) reverse engineering of the Software is strictly
prohibited as further detailed therein.
Server Use. You may install one copy of the Software on your computer file server for
(b)
the purpose of downloading and installing the Software onto other computers within your
internal network up to the Permitted Number of computers. If you have licensed SchemaAgent,
then you may install SchemaAgent Server on any server computer or workstation and use it in
connection with your Software. No other network use is permitted, including without limitation
using the Software either directly or through commands, data or instructions from or to a
computer not part of your internal network, for Internet or Web-hosting services or by any user
not licensed to use this copy of the Software through a valid license from Altova. If you have
purchased Concurrent User Licenses as defined in Section 1(c) you may install a copy of the
Software on a terminal server within your internal network for the sole and exclusive purpose of
permitting individual users within your organization to access and use the Software through a
terminal server session from another computer on the network provided that the total number of
user that access or use the Software on such network or terminal server does not exceed the
Permitted Number. Altova makes no warranties or representations about the performance of
Altova software in a terminal server environment and the foregoing are expressly excluded from
the limited warranty in Section 5 hereof and technical support is not available with respect to
issues arising from use in such an environment.
Concurrent Use. If you have licensed a “Concurrent-User” version of the Software,
(c)
you may install the Software on any compatible computers, up to ten (10) times the Permitted
Number of users, provided that only the Permitted Number of users actually use the Software at
the same time. The Permitted Number of concurrent users shall be delineated at such time as you
elect to purchase the Software licenses.
Backup and Archival Copies. You may make one backup and one archival copy of
(d)
the Software, provided your backup and archival copies are not installed or used on any
computer and further provided that all such copies shall bear the original and unmodified
copyright, patent and other intellectual property markings that appear on or in the Software. You
may not transfer the rights to a backup or archival copy unless you transfer all rights in the
Software as provided under Section 3.
Home Use. You, as the primary user of the computer on which the Software is
(e)
installed, may also install the Software on one of your home computers for your use. However,
the Software may not be used on your home computer at the same time as the Software is being
used on the primary computer.
Key Codes, Upgrades and Updates. Prior to your purchase and as part of the
(f)
registration for the thirty (30) -day evaluation period, as applicable, you will receive an
evaluation key code. You will receive a purchase key code when you elect to purchase the
Software from either Altova GMBH or an authorized reseller. The purchase key code will
enable you to activate the Software beyond the initial evaluation period. You may not re-license,
reproduce or distribute any key code except with the express written permission of Altova. If the
Software that you have licensed is an upgrade or an update, then the update replaces all or part
of the Software previously licensed. The update or upgrade and the associated license keys does
not constitute the granting of a second license to the Software in that you may not use the
upgrade or update in addition to the Software that it is replacing. You agree that use of the
upgrade of update terminates your license to use the Software or portion thereof replaced.
Title. Title to the Software is not transferred to you. Ownership of all copies of the
(g)
Software and of copies made by you is vested in Altova, subject to the rights of use granted to
you in this Software License Agreement. As between you and Altova, documents, files,
stylesheets, generated program code (including the Unrestricted Source Code) and schemas
that are authored or created by you via your utilization of the Software, in accordance with its
Documentation and the terms of this Software License Agreement, are your property.
Reverse Engineering. Except and to the limited extent as may be otherwise
(h)
specifically provided by applicable law in the European Union, you may not reverse engineer,
decompile, disassemble or otherwise attempt to discover the source code, underlying ideas,
© 2008 Altova GmbH
Altova MapForce 2008
338
Appendices
License Information
underlying user interface techniques or algorithms of the Software by any means whatsoever,
directly or indirectly, or disclose any of the foregoing, except to the extent you may be expressly
permitted to decompile under applicable law in the European Union, if it is essential to do so in
order to achieve operability of the Software with another software program, and you have first
requested Altova to provide the information necessary to achieve such operability and Altova
has not made such information available. Altova has the right to impose reasonable conditions
and to request a reasonable fee before providing such information. Any information supplied by
Altova or obtained by you, as permitted hereunder, may only be used by you for the purpose
described herein and may not be disclosed to any third party or used to create any software
which is substantially similar to the expression of the Software. Requests for information from
users in the European Union with respect to the above should be directed to the Altova
Customer Support Department.
Other Restrictions. You may not loan, rent, lease, sublicense, distribute or otherwise
(i)
transfer all or any portion of the Software to third parties except to the limited extent set forth in
Section 3 or otherwise expressly provided. You may not copy the Software except as expressly
set forth above, and any copies that you are permitted to make pursuant to this Software License
Agreement must contain the same copyright, patent and other intellectual property markings that
appear on or in the Software. You may not modify, adapt or translate the Software. You may
not, directly or indirectly, encumber or suffer to exist any lien or security interest on the
Software; knowingly take any action that would cause the Software to be placed in the public
domain; or use the Software in any computer environment not specified in this Software License
Agreement. You will comply with applicable law and Altova’s instructions regarding the use of
the Software. You agree to notify your employees and agents who may have access to the
Software of the restrictions contained in this Software License Agreement and to ensure their
compliance with these restrictions. YOU AGREE THAT YOU ARE SOLELY RESPONSIBLE
FOR THE ACCURACY AND ADEQUACY OF THE SOFTWARE FOR YOUR INTENDED
USE AND YOU WILL INDEMNIFY AND HOLD HARMLESS ALTOVA FROM ANY 3RD
PARTY SUIT TO THE EXTENT BASED UPON THE ACCURACY AND ADEQUACY OF
THE SOFTWARE IN YOUR USE. WITHOUT LIMITATION, THE SOFTWARE IS NOT
INTENDED FOR USE IN THE OPERATION OF NUCLEAR FACILITIES, AIRCRAFT
NAVIGATION, COMMUNICATION SYSTEMS OR AIR TRAFFIC CONTROL EQUIPMENT,
WHERE THE FAILURE OF THE SOFTWARE COULD LEAD TO DEATH, PERSONAL
INJURY OR SEVERE PHYSICAL OR ENVIRONMENTAL DAMAGE.
2.
INTELLECTUAL PROPERTY RIGHTS
Acknowledgement of Altova's Rights. You acknowledge that the Software and any copies that
you are authorized by Altova to make are the intellectual property of and are owned by Altova
and its suppliers. The structure, organization and code of the Software are the valuable trade
secrets and confidential information of Altova and its suppliers. The Software is protected by
copyright, including without limitation by United States Copyright Law, international treaty
provisions and applicable laws in the country in which it is being used. You acknowledge that
Altova retains the ownership of all patents, copyrights, trade secrets, trademarks and other
intellectual property rights pertaining to the Software, and that Altova’s ownership rights extend
to any images, photographs, animations, videos, audio, music, text and “applets” incorporated
into the Software and all accompanying printed materials. You will take no actions which
adversely affect Altova’s intellectual property rights in the Software. Trademarks shall be used
in accordance with accepted trademark practice, including identification of trademark owners’
names. Trademarks may only be used to identify printed output produced by the Software, and
such use of any trademark does not give you any right of ownership in that trademark. XMLSpy,
Authentic, StyleVision, MapForce, Markup Your Mind, Axad, Nanonull, and Altova are
trademarks of Altova GmbH (registered in numerous countries). Unicode and the Unicode Logo
are trademarks of Unicode, Inc. Windows, Windows 95, Windows 98, Windows NT, Windows
2000 and Windows XP are trademarks of Microsoft. W3C, CSS, DOM, MathML, RDF,
XHTML, XML and XSL are trademarks (registered in numerous countries) of the World Wide
Web Consortium (W3C); marks of the W3C are registered and held by its host institutions, MIT,
INRIA and Keio. Except as expressly stated above, this Software License Agreement does not
Altova MapForce 2008
© 2008 Altova GmbH
Appendices
License Information
339
grant you any intellectual property rights in the Software. Notifications of claimed copyright
infringement should be sent to Altova’s copyright agent as further provided on the Altova Web
Site.
3.
LIMITED TRANSFER RIGHTS
Notwithstanding the foregoing, you may transfer all your rights to use the Software to another
person or legal entity provided that: (a) you also transfer each of this Software License
Agreement, the Software and all other software or hardware bundled or pre-installed with the
Software, including all copies, updates and prior versions, and all copies of font software
converted into other formats, to such person or entity; (b) you retain no copies, including
backups and copies stored on a computer; (c) the receiving party secures a personalized key
code from Altova; and (d) the receiving party accepts the terms and conditions of this Software
License Agreement and any other terms and conditions upon which you legally purchased a
license to the Software. Notwithstanding the foregoing, you may not transfer education,
pre-release, or not-for-resale copies of the Software.
4.
PRE-RELEASE AND EVALUATION PRODUCT ADDITIONAL TERMS
If the product you have received with this license is pre-commercial release or beta Software
(“Pre-release Software”), then this Section applies. In addition, this section applies to all
evaluation and/or demonstration copies of Altova software (“Evaluation Software”) and
continues in effect until you purchase a license. To the extent that any provision in this section is
in conflict with any other term or condition in this Software License Agreement, this section
shall supersede such other term(s) and condition(s) with respect to the Pre-release and/or
Evaluation Software, but only to the extent necessary to resolve the conflict. You acknowledge
that the Pre-release Software is a pre-release version, does not represent final product from
Altova, and may contain bugs, errors and other problems that could cause system or other
failures and data loss. CONSEQUENTLY, THE PRE-RELEASE AND/OR EVALUATION
SOFTWARE IS PROVIDED TO YOU “AS-IS” WITH NO WARRANTIES FOR USE OR
PERFORMANCE, AND ALTOVA DISCLAIMS ANY WARRANTY OR LIABILITY
OBLIGATIONS TO YOU OF ANY KIND, WHETHER EXPRESS OR IMPLIED. WHERE
LEGALLY LIABILITY CANNOT BE EXCLUDED FOR PRE-RELEASE AND/OR
EVALUATION SOFTWARE, BUT IT MAY BE LIMITED, ALTOVA’S LIABILITY AND
THAT OF ITS SUPPLIERS SHALL BE LIMITED TO THE SUM OF FIFTY DOLLARS
(USD $50) IN TOTAL. If the Evaluation Software has a time-out feature, then the software will
cease operation after the conclusion of the designated evaluation period. Upon such expiration
date, your license will expire unless otherwise extended. Access to any files created with the
Evaluation Software is entirely at your risk. You acknowledge that Altova has not promised or
guaranteed to you that Pre-release Software will be announced or made available to anyone in
the future, that Altova has no express or implied obligation to you to announce or introduce the
Pre-release Software, and that Altova may not introduce a product similar to or compatible with
the Pre-release Software. Accordingly, you acknowledge that any research or development that
you perform regarding the Pre-release Software or any product associated with the Pre-release
Software is done entirely at your own risk. During the term of this Software License Agreement,
if requested by Altova, you will provide feedback to Altova regarding testing and use of the
Pre-release Software, including error or bug reports. If you have been provided the Pre-release
Software pursuant to a separate written agreement, your use of the Software is governed by such
agreement. You may not sublicense, lease, loan, rent, distribute or otherwise transfer the
Pre-release Software. Upon receipt of a later unreleased version of the Pre-release Software or
release by Altova of a publicly released commercial version of the Software, whether as a
stand-alone product or as part of a larger product, you agree to return or destroy all earlier
Pre-release Software received from Altova and to abide by the terms of the license agreement
for any such later versions of the Pre-release Software.
5.
LIMITED WARRANTY AND LIMITATION OF LIABILITY
Limited Warranty and Customer Remedies. Altova warrants to the person or entity
(a)
© 2008 Altova GmbH
Altova MapForce 2008
340
Appendices
License Information
that first purchases a license for use of the Software pursuant to the terms of this Software
License Agreement that (i) the Software will perform substantially in accordance with any
accompanying Documentation for a period of ninety (90) days from the date of receipt, and (ii)
any support services provided by Altova shall be substantially as described in Section 6 of this
agreement. Some states and jurisdictions do not allow limitations on duration of an implied
warranty, so the above limitation may not apply to you. To the extent allowed by applicable law,
implied warranties on the Software, if any, are limited to ninety (90) days. Altova’s and its
suppliers’ entire liability and your exclusive remedy shall be, at Altova’s option, either (i) return
of the price paid, if any, or (ii) repair or replacement of the Software that does not meet Altova’s
Limited Warranty and which is returned to Altova with a copy of your receipt. This Limited
Warranty is void if failure of the Software has resulted from accident, abuse, misapplication,
abnormal use, Trojan horse, virus, or any other malicious external code. Any replacement
Software will be warranted for the remainder of the original warranty period or thirty (30) days,
whichever is longer. This limited warranty does not apply to Evaluation and/or Pre-release
Software.
No Other Warranties and Disclaimer. THE FOREGOING LIMITED WARRANTY
(b)
AND REMEDIES STATE THE SOLE AND EXCLUSIVE REMEDIES FOR ALTOVA OR
ITS SUPPLIER’S BREACH OF WARRANTY. ALTOVA AND ITS SUPPLIERS DO NOT
AND CANNOT WARRANT THE PERFORMANCE OR RESULTS YOU MAY OBTAIN BY
USING THE SOFTWARE. EXCEPT FOR THE FOREGOING LIMITED WARRANTY, AND
FOR ANY WARRANTY, CONDITION, REPRESENTATION OR TERM TO THE EXTENT
WHICH THE SAME CANNOT OR MAY NOT BE EXCLUDED OR LIMITED BY LAW
APPLICABLE TO YOU IN YOUR JURISDICTION, ALTOVA AND ITS SUPPLIERS
MAKE NO WARRANTIES, CONDITIONS, REPRESENTATIONS OR TERMS, EXPRESS
OR IMPLIED, WHETHER BY STATUTE, COMMON LAW, CUSTOM, USAGE OR
OTHERWISE AS TO ANY OTHER MATTERS. TO THE MAXIMUM EXTENT
PERMITTED BY APPLICABLE LAW, ALTOVA AND ITS SUPPLIERS DISCLAIM ALL
OTHER WARRANTIES AND CONDITIONS, EITHER EXPRESS OR IMPLIED,
INCLUDING,
BUT
NOT
LIMITED
TO,
IMPLIED
WARRANTIES
OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, SATISFACTORY
QUALITY, INFORMATIONAL CONTENT OR ACCURACY, QUIET ENJOYMENT, TITLE
AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE, AND THE
PROVISION OF OR FAILURE TO PROVIDE SUPPORT SERVICES. THIS LIMITED
WARRANTY GIVES YOU SPECIFIC LEGAL RIGHTS. YOU MAY HAVE OTHERS,
WHICH VARY FROM STATE/JURISDICTION TO STATE/JURISDICTION.
Limitation Of Liability. TO THE MAXIMUM EXTENT PERMITTED BY
(c)
APPLICABLE LAW EVEN IF A REMEDY FAILS ITS ESSENTIAL PURPOSE, IN NO
EVENT SHALL ALTOVA OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL,
INCIDENTAL, DIRECT, INDIRECT OR CONSEQUENTIAL DAMAGES WHATSOEVER
(INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS,
BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR ANY OTHER
PECUNIARY LOSS) ARISING OUT OF THE USE OF OR INABILITY TO USE THE
SOFTWARE OR THE PROVISION OF OR FAILURE TO PROVIDE SUPPORT SERVICES,
EVEN IF ALTOVA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
IN ANY CASE, ALTOVA’S ENTIRE LIABILITY UNDER ANY PROVISION OF THIS
SOFTWARE LICENSE AGREEMENT SHALL BE LIMITED TO THE AMOUNT
ACTUALLY PAID BY YOU FOR THE SOFTWARE PRODUCT. Because some states and
jurisdictions do not allow the exclusion or limitation of liability, the above limitation may not
apply to you. In such states and jurisdictions, Altova’s liability shall be limited to the greatest
extent permitted by law and the limitations or exclusions of warranties and liability contained
herein do not prejudice applicable statutory consumer rights of person acquiring goods otherwise
than in the course of business. The disclaimer and limited liability above are fundamental to this
Software License Agreement between Altova and you.
Infringement Claims. Altova will indemnify and hold you harmless and will defend or
(d)
settle any claim, suit or proceeding brought against you by a third party that is based upon a
claim that the content contained in the Software infringes a copyright or violates an intellectual
Altova MapForce 2008
© 2008 Altova GmbH
Appendices
License Information
341
or proprietary right protected by United States or European Union law (“Claim”), but only to the
extent the Claim arises directly out of the use of the Software and subject to the limitations set
forth in Section 5 of this Agreement except as otherwise expressly provided. You must notify
Altova in writing of any Claim within ten (10) business days after you first receive notice of the
Claim, and you shall provide to Altova at no cost with such assistance and cooperation as Altova
may reasonably request from time to time in connection with the defense of the Claim. Altova
shall have sole control over any Claim (including, without limitation, the selection of counsel
and the right to settle on your behalf on any terms Altova deems desirable in the sole exercise of
its discretion). You may, at your sole cost, retain separate counsel and participate in the defense
or settlement negotiations. Altova shall pay actual damages, costs, and attorney fees awarded
against you (or payable by you pursuant to a settlement agreement) in connection with a Claim
to the extent such direct damages and costs are not reimbursed to you by insurance or a third
party, to an aggregate maximum equal to the purchase price of the Software. If the Software or
its use becomes the subject of a Claim or its use is enjoined, or if in the opinion of Altova’s legal
counsel the Software is likely to become the subject of a Claim, Altova shall attempt to resolve
the Claim by using commercially reasonable efforts to modify the Software or obtain a license to
continue using the Software. If in the opinion of Altova’s legal counsel the Claim, the injunction
or potential Claim cannot be resolved through reasonable modification or licensing, Altova, at its
own election, may terminate this Software License Agreement without penalty, and will refund
to you on a pro rata basis any fees paid in advance by you to Altova. THE FOREGOING
CONSTITUTES ALTOVA’S SOLE AND EXCLUSIVE LIABILITY FOR INTELLECTUAL
PROPERTY INFRINGEMENT. This indemnity does not apply to infringements that would not
be such, except for customer-supplied elements.
6.
SUPPORT AND MAINTENANCE
Altova offers multiple optional “Support & Maintenance Package(s)” (“SMP”) for the version of
Software product edition that you have licensed, which you may elect to purchase in addition to
your Software license. The Support Period, hereinafter defined, covered by such SMP shall be
delineated at such time as you elect to purchase a SMP. Your rights with respect to support and
maintenance as well as your upgrade eligibility depend on your decision to purchase SMP and
the level of SMP that you have purchased:
(a)
If you have not purchased SMP, you will receive the Software AS IS and will not
receive any maintenance releases or updates. However, Altova, at its option and in its sole
discretion on a case by case basis, may decide to offer maintenance releases to you as a courtesy,
but these maintenance releases will not include any new features in excess of the feature set at
the time of your purchase of the Software. In addition, Altova will provide free technical support
to you for thirty (30) days after the date of your purchase (the “Support Period” for the purposes
of this paragraph a), and Altova, in its sole discretion on a case by case basis, may also provide
free courtesy technical support during your thirty (30)-day evaluation period. Technical support
is provided via a Web-based support form only, and there is no guaranteed response time.
(b)
If you have purchased SMP, then solely for the duration of its delineated Support
Period, you are eligible to receive the version of the Software edition that you have licensed
and all maintenance releases and updates for that edition that are released during your Support
Period. For the duration of your SMP’s Support Period, you will also be eligible to receive
upgrades to the comparable edition of the next version of the Software that succeeds the
Software edition that you have licensed for applicable upgrades released during your Support
Period. The specific upgrade edition that you are eligible to receive based on your Support
Period is further detailed in the SMP that you have purchased. Software that is introduced as
separate product is not included in SMP. Maintenance releases, updates and upgrades may or
may not include additional features. In addition, Altova will provide Priority Technical Support
to you for the duration of the Support Period. Priority Technical Support is provided via a
Web-based support form only, and Altova will make commercially reasonable efforts to respond
via e-mail to all requests within forty-eight (48) hours during Altova’s business hours (MO-FR,
8am UTC – 10pm UTC, Austrian and US holidays excluded) and to make reasonable efforts to
provide work-arounds to errors reported in the Software.
© 2008 Altova GmbH
Altova MapForce 2008
342
Appendices
License Information
During the Support Period you may also report any Software problem or error to Altova. If
Altova determines that a reported reproducible material error in the Software exists and
significantly impairs the usability and utility of the Software, Altova agrees to use reasonable
commercial efforts to correct or provide a usable work-around solution in an upcoming
maintenance release or update, which is made available at certain times at Altova’s sole
discretion.
If Altova, in its discretion, requests written verification of an error or malfunction discovered by
you or requests supporting example files that exhibit the Software problem, you shall promptly
provide such verification or files, by email, telecopy, or overnight mail, setting forth in
reasonable detail the respects in which the Software fails to perform. You shall use reasonable
efforts to cooperate in diagnosis or study of errors. Altova may include error corrections in
maintenance releases, updates, or new major releases of the Software. Altova is not obligated to
fix errors that are immaterial. Immaterial errors are those that do not significantly impact use of
the Software. Whether or not you have purchased the Support & Maintenance Package,
technical support only covers issues or questions resulting directly out of the operation of the
Software and Altova will not provide you with generic consultation, assistance, or advice under
any circumstances.
Updating Software may require the updating of software not covered by this Software License
Agreement before installation. Updates of the operating system and application software not
specifically covered by this Software License Agreement are your responsibility and will not be
provided by Altova under this Software License Agreement. Altova’s obligations under this
Section 6 are contingent upon your proper use of the Software and your compliance with the
terms and conditions of this Software License Agreement at all times. Altova shall be under no
obligation to provide the above technical support if, in Altova’s opinion, the Software has failed
due to the following conditions: (i) damage caused by the relocation of the software to another
location or CPU; (ii) alterations, modifications or attempts to change the Software without
Altova’s written approval; (iii) causes external to the Software, such as natural disasters, the
failure or fluctuation of electrical power, or computer equipment failure; (iv) your failure to
maintain the Software at Altova’s specified release level; or (v) use of the Software with other
software without Altova’s prior written approval. It will be your sole responsibility to: (i)
comply with all Altova-specified operating and troubleshooting procedures and then notify
Altova immediately of Software malfunction and provide Altova with complete information
thereof; (ii) provide for the security of your confidential information; (iii) establish and maintain
backup systems and procedures necessary to reconstruct lost or altered files, data or programs.
7.
SOFTWARE ACTIVATION, UPDATES AND LICENSE METERING
License Metering. Altova has a built-in license metering module that helps you to
(a)
avoid any unintentional violation of this Software License Agreement. Altova may use your
internal network for license metering between installed versions of the Software.
Software Activation. Altova’s Software may use your internal network and
(b)
Internet connection for the purpose of transmitting license-related data at the time of
installation, registration, use, or update to an Altova-operated license server and
validating the authenticity of the license-related data in order to protect Altova against
unlicensed or illegal use of the Software and to improve customer service. Activation is
based on the exchange of license related data between your computer and the Altova
license server. You agree that Altova may use these measures and you agree to follow any
applicable requirements.
LiveUpdate. Altova provides a new LiveUpdate notification service to you, which is
(c)
free of charge. Altova may use your internal network and Internet connection for the purpose of
transmitting license-related data to an Altova-operated LiveUpdate server to validate your
license at appropriate intervals and determine if there is any update available for you.
Use of Data. The terms and conditions of the Privacy Policy are set out in full at
(d)
http://www.altova.com/privacy and are incorporated by reference into this Software License
Agreement. By your acceptance of the terms of this Software License Agreement or use of the
Software, you authorize the collection, use and disclosure of information collected by Altova for
the purposes provided for in this Software License Agreement and/or the Privacy Policy as
Altova MapForce 2008
© 2008 Altova GmbH
Appendices
License Information
343
revised from time to time. European users understand and consent to the processing of personal
information in the United States for the purposes described herein. Altova has the right in its
sole discretion to amend this provision of the Software License Agreement and/or Privacy
Policy at any time. You are encouraged to review the terms of the Privacy Policy as posted on
the Altova Web site from time to time.
8.
TERM AND TERMINATION
This Software License Agreement may be terminated (a) by your giving Altova written notice of
termination; or (b) by Altova, at its option, giving you written notice of termination if you
commit a breach of this Software License Agreement and fail to cure such breach within ten (10)
days after notice from Altova or (c) at the request of an authorized Altova reseller in the event
that you fail to make your license payment or other monies due and payable.. In addition the
Software License Agreement governing your use of a previous version that you have upgraded
or updated of the Software is terminated upon your acceptance of the terms and conditions of the
Software License Agreement accompanying such upgrade or update. Upon any termination of
the Software License Agreement, you must cease all use of the Software that it governs, destroy
all copies then in your possession or control and take such other actions as Altova may
reasonably request to ensure that no copies of the Software remain in your possession or control.
The terms and conditions set forth in Sections 1(g), (h), (i), 2, 5(b), (c), 9, 10 and 11 survive
termination as applicable.
9.
RESTRICTED RIGHTS NOTICE AND EXPORT RESTRICTIONS
The Software was developed entirely at private expense and is commercial computer software
provided with RESTRICTED RIGHTS. Use, duplication or disclosure by the U.S.
Government or a U.S. Government contractor or subcontractor is subject to the restrictions set
forth in this Agreement and as provided in FAR 12.211 and 12.212 (48 C.F.R. §12.211 and
12.212) or DFARS 227. 7202 (48 C.F.R. §227-7202) as applicable. Consistent with the above
as applicable, Commercial Computer Software and Commercial Computer Documentation
licensed to U.S. government end users only as commercial items and only with those rights as
are granted to all other end users under the terms and conditions set forth in this Software
License Agreement. Manufacturer is Altova GmbH, Rudolfsplatz, 13a/9, A-1010 Vienna,
Austria/EU. You may not use or otherwise export or re-export the Software or Documentation
except as authorized by United States law and the laws of the jurisdiction in which the Software
was obtained. In particular, but without limitation, the Software or Documentation may not be
exported or re-exported (i) into (or to a national or resident of) any U.S. embargoed country or
(ii) to anyone on the U.S. Treasury Department's list of Specially Designated Nationals or the
U.S. Department of Commerce's Table of Denial Orders. By using the Software, you represent
and warrant that you are not located in, under control of, or a national or resident of any such
country or on any such list.
10.
THIRD PARTY SOFTWARE
The Software may contain third party software which requires notices and/or additional terms
and conditions. Such required third party software notices and/or additional terms and
conditions are located Our Website at http://www.altova.com/legal_3rdparty.html and are made
a part of and incorporated by reference into this Agreement. By accepting this Agreement, you
are also accepting the additional terms and conditions, if any, set forth therein.
11.
GENERAL PROVISIONS
If you are located in the European Union and are using the Software in the European Union and
not in the United States, then this Software License Agreement will be governed by and
construed in accordance with the laws of the Republic of Austria (excluding its conflict of laws
principles and the U.N. Convention on Contracts for the International Sale of Goods) and you
expressly agree that exclusive jurisdiction for any claim or dispute with Altova or relating in any
way to your use of the Software resides in the Handelsgericht, Wien (Commercial Court,
© 2008 Altova GmbH
Altova MapForce 2008
344
Appendices
License Information
Vienna) and you further agree and expressly consent to the exercise of personal jurisdiction in
the Handelsgericht, Wien (Commercial Court, Vienna) in connection with any such dispute or
claim.
If you are located in the United States or are using the Software in the United States then this
Software License Agreement will be governed by and construed in accordance with the laws of
the Commonwealth of Massachusetts, USA (excluding its conflict of laws principles and the
U.N. Convention on Contracts for the International Sale of Goods) and you expressly agree that
exclusive jurisdiction for any claim or dispute with Altova or relating in any way to your use of
the Software resides in the federal or state courts of Massachusetts and you further agree and
expressly consent to the exercise of personal jurisdiction in the federal or state courts of
Massachusetts in connection with any such dispute or claim.
If you are located outside of the European Union or the United States and are not using the
Software in the United States, then this Software License Agreement will be governed by and
construed in accordance with the laws of the Republic of Austria (excluding its conflict of laws
principles and the U.N. Convention on Contracts for the International Sale of Goods) and you
expressly agree that exclusive jurisdiction for any claim or dispute with Altova or relating in any
way to your use of the Software resides in the Handelsgericht, Wien (Commercial Court,
Vienna) and you further agree and expressly consent to the exercise of personal jurisdiction in
the Handelsgericht Wien (Commercial Court, Vienna) in connection with any such dispute or
claim. This Software License Agreement will not be governed by the conflict of law rules of any
jurisdiction or the United Nations Convention on Contracts for the International Sale of Goods,
the application of which is expressly excluded.
This Software License Agreement contains the entire agreement and understanding of the parties
with respect to the subject matter hereof, and supersedes all prior written and oral
understandings of the parties with respect to the subject matter hereof. Any notice or other
communication given under this Software License Agreement shall be in writing and shall have
been properly given by either of us to the other if sent by certified or registered mail, return
receipt requested, or by overnight courier to the address shown on Altova’s Web site for Altova
and the address shown in Altova’s records for you, or such other address as the parties may
designate by notice given in the manner set forth above. This Software License Agreement will
bind and inure to the benefit of the parties and our respective heirs, personal and legal
representatives, affiliates, successors and permitted assigns. The failure of either of us at any
time to require performance of any provision hereof shall in no manner affect such party’s right
at a later time to enforce the same or any other term of this Software License Agreement. This
Software License Agreement may be amended only by a document in writing signed by both of
us. In the event of a breach or threatened breach of this Software License Agreement by either
party, the other shall have all applicable equitable as well as legal remedies. Each party is duly
authorized and empowered to enter into and perform this Software License Agreement. If, for
any reason, any provision of this Software License Agreement is held invalid or otherwise
unenforceable, such invalidity or unenforceability shall not affect the remainder of this Software
License Agreement, and this Software License Agreement shall continue in full force and effect
to the fullest extent allowed by law. The parties knowingly and expressly consent to the
foregoing terms and conditions.
Last updated: 2006-09-05
Altova MapForce 2008
© 2008 Altova GmbH
Index
Index
A
345
Assign,
global resource to component, 91
ATTLIST,
DTD namespace URIs, 129
Autoconnect,
child items, 81
Auto-mapping,
child elements, 81
About MapForce, 192
Accelerator,
shortcut keys, 186
Activating the software, 191
Active, 212
ActiveDocument, 207, 223
Add,
global resource file, 88
schema location, 177
user-def. functions, 134
Aggregate,
function - using named templates, 167
functions, 114
Alternative,
input data, 122
Altova Engines,
in Altova products, 328
Altova website, 192
Altova XML Parser,
about, 327
B
Background,
with gradient, 231
Background Information, 325
backwards compatibility,
of XSLT 2.0 Engine, 322
Base package name,
for Java, 219
Bool,
boolean values in XSLT, 117
output if false, 154
Boolean,
comparing input nodes, 119
values in XSLT, 117
Builder,
user-defined function, 134
Altova XSLT 1.0 Engine,
limitations and implementation-specific behavior, 320
Altova XSLT 2.0 Engine,
general information about, 322
information about, 322
Annotation,
connector, 180
Annotation settings,
connector, 70
API,
accessing, 294
documentation, 194
overview, 195
Application, 206, 207
for Documents, 222
Application object, 196, 207
Application workflow,
using global resources, 97
Application-level,
integration of MapForce, 259
© 2008 Altova GmbH
C
C#,
code generation, 216
enumeration, 254
error handling, 203
integration of MapForce, 268, 269, 271, 273, 274
options, 228, 230
C++,
code generation, 217
enumeration, 250, 251
error handling, 203
options, 228, 229, 230
Call,
template, 163
Change,
configuration - global resource, 92
346
Index
character entities,
in HTML output of XSLT transformation, 320
deleted items, 23
encoding, 15
Check,
type checking, 130
encoding settings, 177
exception, 131
Child items,
autoconnect, 81
item context menu, 15
pretty pring in output, 177
Deleting, 81
schema, 15
Children,
standard with children, 76
Component download center,
at Altova web site, 192
Class ID,
in MapForce integration, 260
Configuration,
add to global resource, 88
copy existing, 88
Close, 216
project, 235
Code,
strip schema names from, 177
code generation, 224, 226
and absolute path, 50
and input parameters, 122
C#, 216
C++, 217
enumerations, 250, 251, 252, 254, 255
input parameters, 122
switch - global resource, 92
Connection,
Deleting, 81
properties, 81
settings, 180
Connections,
type driven, 78
Connector,
annotate, 70
mapping with, 21
Java, 217
options, 220
naming, 180
popup, 21
options for, 228, 229, 230
sample, 197
properties, 81
wrapper class version, 186
XSLT, 218
Code-generation,
options for, 209, 232
COM-API,
documentation, 194
Command line,
parameters, 121
parameters and input values, 122
Companion software,
for download, 192
compl.,
complement node set, 44
Complex,
function - inline, 138
User-defined complex input, 145
User-defined complex output, 150
User-defined function, 144, 149
Component,
assign global resource, 91
change database, 177
changing settings, 177
Connector icon,
popup, 21
Connectors,
copy-all, 78
Constructor,
XSLT2, 166
Context,
priority, 18
priority context, 120
Context menu,
item context menu, 15
Conversion,
functions - boolean, 119
type checking, 130
Copy all,
mapping method, 66
Copy-all,
and filters, 78
connectors, 78
Copyright information, 332
Count, 222
count() function,
in XPath 1.0, 320
© 2008 Altova GmbH
Index
count, sum, avg,
aggregate function, 114
Create,
function, 40
user-defined function, 134
Custom,
function, 18
lilbrary, 18
XSLT 2.0 functions, 166
XSLT functions, 163
D
Data,
filtering, 44
Database,
and multiple sources, 177
change DB, 177
component, 15
strip schema names from code, 177
Datatype,
explicit - implicit, 166
Date,
XSLT 2.0 constructor, 166
Default,
configuration - global resource, 88
input value, 154
default functions namespace,
in XSLT 2.0 stylesheets, 322
Definition file,
globalresource.xml, 86
Delete,
connections, 81
deletions - missing items, 23
user-defined function, 134
Distribution,
of Altova's software products, 332, 333, 335
Document, 215
closing, 216
creating new, 208, 223
filename, 220
on closing, 215
on opening, 207
opening, 209, 223
path and name of, 216
path to, 220
© 2008 Altova GmbH
347
retrieving active document, 223
save, 221
save as, 221
Document-level,
examples of integration of MapForce, 268
integration of MapForce, 263, 264, 265, 266, 267
Documents, 208, 222
retrieving, 222
total number in collection, 222
DOM type,
enumerations for C++, 250
for C++, 229
Driver,
JDBC, 177
DTD,
source and target, 129
Duplicate,
input item, 59
E
EDI,
validating, 27
Edit, 175
Encoding,
component, 15
component settings, 177
default for output files, 230
End User License Agreement, 332, 336
Enumerations, 248, 250, 251, 252, 254
for MapForce View, 255
in MapForceControl, 315
Erase,
delete user-defined func., 134
Error,
defining exceptions, 131
validation, 27
Error handling,
general description, 203
ErrorMarkers, 224, 226
Evaluation key,
for your Altova software, 191
Evaluation period,
of Altova's software products, 332, 333, 335
Events,
of Document, 215
348
Events for Project, 234
Examples,
tutorial folder, 32
Exception,
throw, 131
Exist,
use not-exist to map missing nodes, 127
Exists,
node test, 125
Explicit,
datatype, 166
Export,
user-defined function, 134
Extending,
function parameters, 18
F
FAQs on MapForce, 192
File, 173
add resource configuration, 88
define global resource, 88
Filter,
complement, 44
Index
Query, 18
restrictions in user-defined, 134
standard user-defined function, 140
sum, 167
user-defined, 134
user-defined - changing type, 134
user-defined look-up function, 140
visual builder, 134
functions,
importing user-defined, 134
mapping to, 40
see under XSLT 2.0 functions, 324
G
Generate,
multiple target Java, 53
multiple target XSLT, 53
XML Schema automatically, 34
XSLT, 29
Global resource,
activate, 92
assign to component, 91
copy configuration, 88
copy-all connector, 78
default configuration, 88
data, 44
folders as, 94
properties, 104
start workflow, 101
Find,
XSLT - Output tab, 175
Folders,
as a global resource, 94
FullName, 216, 236
Function, 182
adding, 18
adding custom XSLT, 163
adding custom XSLT 2.0, 166
aggregate, 114
Changing type of user-defined, 134
complex - inline, 138
conversion - boolean, 119
custom, 18
workflow, 97
Global resources,
define resource file, 88
definition file, 86
toolbar, 87
Globalresource.xml,
resource definition, 86
Gradients,
in background, 231
Groups,
loops and hierarchies, 30
exporting user-defined, 134
extendable, 18
inline, 138
input as parameter, 122
H
library, 18
Help,
see Onscreen Help, 190
nested user-defined, 154
© 2008 Altova GmbH
Index
Help menu, 189
Hierarchies,
loops and groups, 30
HighlightMyConnections, 212
HighlightMyConnectionsRecursively, 213
Hotkeys,
shortcuts, 186
How to..., 108
HRESULT,
and error handling, 203
HTML,
integration of MapForce, 276, 277, 278, 279
349
input XML instance, 177
output XML instance, 177
Integrating,
MapForce in applications, 258
Internet usage,
in Altova products, 331
Introduction to MapForce, 3
Item, 222
context menu, 15
duplicating, 59
missing, 23
schema - mapping, 37
HTML example,
of MapForceControl integration, 260, 261
Iteration,
priority context, 120
I
J
implementation-specific behavior,
of XSLT 2.0 functions, 324
Java,
code generation, 217
generate multiple target, 53
Implicit,
datatype, 166
Import,
user-def. functions, 134
Include,
XSLT, 163
XSLT 2.0, 166
Inline, 134
Inline / Standard,
user-defined functions, 138
Input,
as command line param, 122
comparing boolean nodes, 119
default value, 154
optional parameters, 154
XML instance, 177
multiple targets, 50
options, 219, 228
JavaScript,
error handling, 203
JScript,
code-generation sample, 197
K
Keyboard,
shortcuts, 186
Key-codes,
for your Altova software, 191
Input icon,
mapping, 21
Input parameters,
and code generation, 122
L
Insert, 176
Label,
connector, 70
InsertXMLFile, 213
InsertXMLSchema, 213
InsertXMLSchemaWithSample, 213
Installation,
examples folder, 32
Instance,
© 2008 Altova GmbH
last() function,
in XPath 1.0, 320
Legal information, 332
Libraries,
and user-defined functions, 134
350
Library,
adding XSLT 2.0 functions, 166
adding XSLT functions, 163
custom, 18
Index
in MapForceControl, 298
MapForceControl,
documentation of, 258
example of integration at application level, 260, 261
function, 18
import user-def. functions, 134
examples of integration at document level, 268
in MapForceControl, 299
XPath2, 18
integration at application level, 259
integration at document level, 263, 264, 265, 266, 267
Library type,
enumerations for C++, 251
for C++, 228, 229, 230
License, 336
information about, 332
integration using C#, 268, 269, 271, 273, 274
integration using HTML, 276, 277, 278, 279
integration using Visual Basic, 279
object reference, 295
License metering,
in Altova products, 334
MapForceControlDocument,
in MapForceControl, 306
Licenses,
for your Altova software, 191
MapForceControlPlaceHolder,
in MapForceControl, 313
Logo,
display on startup, 231
MapForceView, 212, 219
application, 212
option for printing, 231
Lookup table,
mapping missing nodes, 127
properties, 112
value map table, 109
Loops,
groups and hierarchies, 30
M
MapForce,
API, 194
integration, 258
introduction, 3
Overview, 10
parent, 214
terminology, 12
MapForce API, 194
accessing, 294
overview, 195
MapForce API Type Library, 205
MapForce integration,
example of, 260, 261
MapForce view,
enumerations for, 255
MapForceCommand,
in MapForceControl, 296
MapForceCommands,
Mapping,
boolean values, 117
child elements, 81
connnector, 21
creating source driven, 70
inserting XML file, 213
inserting XML Schema file, 213
no. of connections, 21
properties, 81
schema items, 37
source driven - mixed content, 67
standard mapping, 76
target driven, 76
tutorial, 32
type driven, 78
validate result, 27
validation, 27
Mapping methods,
standard / mixed / copy all, 66
Marked items,
missing items, 23
Memory requirements, 326
Menu,
connection, 180
edit, 175
file, 173
function, 182
insert, 176
output, 184
tools, 186
© 2008 Altova GmbH
Index
Menu,
view, 185
MFC support,
fo C++, 230
MFF,
and user-defined functions, 134
351
user-defined functions, 154
NewDocument, 208, 223
NewProject, 209
Node,
comparing boolean, 119
mapping missing nodes, 127
min, max,
aggregate function, 114
removing text nodes, 70
summing multiple, 167
Missing items, 23
testing, 125
Missing nodes,
mapping missing nodes, 127
Node set,
complement, 44
Mixed,
content mapping, 67
content mapping example, 74
Not exist,
mapping missing nodes, 127
content mapping method, 66
create mixed content, 70
source-driven mapping, 67
standard mapping, 76
text nodes, 70
Multiple,
source schemas, 177
target schemas, 50
targets and Java, 50
viewing multiple target schemas, 53
multiple input,
items, 59
Multiple source,
to single target item, 55
MyDocuments,
example files, 32
O
Object,
reference, 205
Object model,
overview, 196
Object tree navigation, 210, 214
Application, 207
Document, 216
MapForceView, 212
Mapping, 220
Options, 228, 231
Project, 235
OnDocumentClosed, 215
OnDocumentOpened, 207
OnProjectClosed, 234
N
Name, 208, 220, 238
connector, 70, 180
Named,
template - namespaces, 163
OnProjectOpened, 207
Onscreen help,
index of, 190
searching, 190
table of contents, 190
OpenDocument, 209, 223
Named template,
summing nodes, 167
OpenProject, 209
Optional,
input parameters, 154
Namespace,
named template, 163
Options, 209, 228
for code generation, 220, 230
Namespace URI,
DTD, 129
for Java, 219
namespaces,
in XSLT 2.0 stylesheet, 322
Ordering Altova software, 191
OS,
for Altova products, 326
Nested,
Output, 184
© 2008 Altova GmbH
352
Output, 184
add schema location to output, 177
parameter, 154
user-defined if bool = false, 154
validate, 27
validating, 27
XML instance, 177
Output directory,
for code-generation files, 228
for XSLT generated output, 232
Output encoding,
default used, 230
Index
for download, 192
Programming language,
enumerations for, 252
Project, 210, 233
creating new, 209
file name, 238
file name and path, 236
on opening, 207
opening, 209
path with filename, 239
saving, 239
Output icon,
mapping, 21
Project type,
enumerations for C#, 254
for C#, 230
Override,
input data, 122
Properties,
value map table, 112
Overview,
of MapForce API, 195
Overview of MapForce, 10
P
Parameter,
alternative value, 122
Q
Quit, 210
R
and code generation, 122
command line, 121
extending in functions, 18
Input function as a, 122
optional, 154
output, 154
Parent, 210, 222, 224, 227, 239
Parser,
built into Altova products, 327
Path, 220, 239
absolute when generating code, 50
Platforms,
for Altova products, 326
Reference, 172
Registering your Altova software, 191
Remove,
Connection, 81
Resource,
folder, 94
global resource properties, 104
Result of Transformation,
global resources, 97
Right-to-left writing systems, 330
Root,
element of target, 116
position() function,
in XPath 1.0, 320
Pretty print,
in output component, 177
S
Priority,
function, 18
Save, 221, 239
XML preview, 29
Priority context,
defining, 120
Processors,
XSLT code, 29
SaveAs, 221
Saved, 221, 239
© 2008 Altova GmbH
Index
353
Schema,
add location to output, 177
auto-generate from XML file, 34
components, 15
database component, 15
multiple source, 177
multiple target, 50
name, strip from generated code, 177
viewing multiple targets, 53
Search,
XSLT - Output tab, 175
Setting,
connector, 180
Settings,
changing component, 177
Shortcut,
keyboard, 186
ShowItemTypes, 214
ShowLibraryFunctionHeader, 214
shutdown,
of application, 210
Software product license, 336
Source-driven,
- mixed content mapping, 67
creating mapping, 70
text node settings, 70
vs. standard mapping, 76
Standard,
mapping method, 66
mapping with children, 76
mixed content mapping, 76
user-defined function, 140
vs source-driven mapping, 76
XSLT library, 18
startup,
of application, 210
Substitute,
missing node, 125
T
Table,
lookup - value map, 109
strip schema names from, 177
Target,
multiple schemas, 50
root element, 116
viewing multiple schemas, 53
Target item,
mapping multi-source, 55
Target-driven,
mapping, 76
Technical Information, 325
Technical support for MapForce, 192
Teminology, 12
Template,
calling, 163
named - summing, 167
Test,
node testing, 125
Text,
nodes in mixed content, 70
removing text nodes, 70
Toolbar,
global resource, 87
Tools, 186
Transform,
input data - value map, 109
Tutorial, 32
examples folder, 32
Type conversion,
checking, 130
Type driven,
connections, 78
Sum,
nodes in XSLT 1.0, 167
Support for MapForce, 192
Switch,
configuration - global resource, 92
U
Unicode,
support in Altova products, 329
Unicode support,
in Altova products, 329, 330
URI,
© 2008 Altova GmbH
354
URI,
in DTDs, 129
User defined,
changing function type, 134
complex input, 145
complex output, 150
deleting, 134
function - inline / standard, 138
function - standard, 140
functions, 134
functions - complex, 144, 149
functions - restrictions, 134
functions changing type of, 134
importing/exporting, 134
look-up functions, 140
nested functions, 154
output if bool = false, 154
User manual,
see also Onscreen Help, 190
User-defined,
functions, 134
functions & mffs, 134
Using,
global resources, 92
Index
Visual function builder, 134
W
Warning,
validation, 27
whitespace in XML document,
handling by Altova XSLT 2.0 Engine, 322
whitespace nodes in XML document,
and handling by XSLT 1.0 Engine, 320
WindowHandle, 211
Windows,
support for Altova products, 326
Workflow,
start - global resource, 101
using global resource, 97
Wrapper classes,
version compatibility, 186
X
XML,
generate XML Schema from, 34
V
Validate,
mapping project, 27
output data, 27
Validator,
in Altova products, 327
Value,
boolean in XSLT, 117
default, 154
Value-Map,
lookup table, 109
lookup table - properties, 112
Version,
wrapper class compatibility, 186
View, 185
of MapForce, 212
Visible, 210
Visual Basic,
error handling, 203
integration of MapForce, 279
XML instance,
absolute path, 50
input, 177
output, 177
XML Parser,
about, 327
XML schema,
automatically generate, 34
XPath,
summing multiple nodes, 167
XPath2,
library, 18
XQuery,
functions, 18
XQuery processor,
in Altova products, 328
xsl:preserve-space, 320
xsl:strip-space, 320
XSLT,
adding custom functions, 163
boolean values, 117
© 2008 Altova GmbH
Index
XSLT,
code generation, 218
generate, 29
generate multiple target, 53
options, 232
standard library, 18
template namespace, 163
XSLT 1.0 Engine,
limitations and implementation-specific behavior, 320
XSLT 1.0/2.0,
generate (tutorial), 48
XSLT 2.0,
adding custom functions, 166
XSLT 2.0 Engine,
general information about, 322
information about, 322
XSLT 2.0 functions,
implementation-specific behavior of, 324
see under fn: for specific functions, 324
XSLT 2.0 stylesheet,
namespace declarations in, 322
XSLT processors,
in Altova products, 328
XSLT2.0,
date constructor, 166
© 2008 Altova GmbH
355